@fui-org/fui-cli 1.3.2 → 2.0.0

package/skills/fui-skill/references/default-function.md

@@ -1,45 +1,45 @@
 # Default Functions
 
-> File này sở hữu: **hàm tiện ích FUI dùng được trong `FUN`/`EXE`/`script.js`** (openWindow, ajaxCALL, jsonToExcel, groupBy...). Vị trí trong source xem [script-map.md](script-map.md).
+> Owns: **FUI utility functions usable in `FUN`/`EXE`/`script.js`** (openWindow, ajaxCALL, jsonToExcel, groupBy...). Source locations: [script-map.md](script-map.md).
 
-Các hàm và biến global được định nghĩa trong `defaultfunction.js` — tự động load trong mọi module FUI V2.
+Globals defined in `defaultfunction.js`, auto-loaded in every FUI V2 module.
 
 ---
 
 ## Global Variables
 
-| Variable | Mô tả |
-|---|---|
-| `$isMobile` | `true` nếu user agent là thiết bị mobile |
-| `$isPhone` | `true` nếu là điện thoại (không tính tablet) |
-| `$isApple` | `true` nếu là thiết bị Apple (iPad, iPhone, iPod) |
+| Variable    | Meaning                                     |
+| ----------- | ------------------------------------------- |
+| `$isMobile` | `true` if mobile user agent                 |
+| `$isPhone`  | `true` if phone (not tablet)                |
+| `$isApple`  | `true` if Apple device (iPad, iPhone, iPod) |
 
 ---
 
-## Dialog & Thông báo
+## Dialogs & Messages
 
 ### confirm(obj)
 
-Hiển thị hộp thoại xác nhận OK/Cancel có style. Wrapper của `$.confirm` (jquery-confirm).
+Styled OK/Cancel dialog; wraps `$.confirm` (jquery-confirm).
 
-| Param | Mô tả |
-|---|---|
-| `title` | Tiêu đề dialog |
-| `message` | Nội dung |
-| `action` | Function chạy khi nhấn OK |
-| `cancel` | Function chạy khi nhấn Cancel (tùy chọn) |
-| `type` | Màu: `'blue'` (mặc định), `'red'`, `'green'`, `'orange'` |
-| `icon` | Icon class, ví dụ `'mdi mdi-delete'` |
+| Param     | Meaning                                                   |
+| --------- | --------------------------------------------------------- |
+| `title`   | Title                                                     |
+| `message` | Body                                                      |
+| `action`  | Function run on OK                                        |
+| `cancel`  | Function run on Cancel (optional)                         |
+| `type`    | Color: `'blue'` (default), `'red'`, `'green'`, `'orange'` |
+| `icon`    | Icon class, e.g. `'mdi mdi-delete'`                       |
 
 ```js
 confirm({
-    title: 'Xác nhận xóa',
-    message: 'Bạn có chắc muốn xóa bản ghi này không?',
-    type: 'red',
-    icon: 'mdi mdi-delete',
-    action: function() {
-        CALL(vueData.actDelete);
-    }
+  title: "Xác nhận xóa",
+  message: "Bạn có chắc muốn xóa bản ghi này không?",
+  type: "red",
+  icon: "mdi mdi-delete",
+  action: function () {
+    CALL(vueData.actDelete);
+  },
 });
 ```
 
@@ -47,31 +47,31 @@ confirm({
 
 ### showMessage(obj)
 
-Hiển thị hộp thoại thông báo (chỉ có nút Close). Wrapper của `$.dialog`.
+Message dialog (Close button only); wraps `$.dialog`.
 
-| Param | Mô tả |
-|---|---|
-| `title` | Tiêu đề |
-| `message` | Nội dung |
-| `type` | Màu: `'blue'`, `'red'`, `'green'` |
-| `icon` | Icon class |
-| `onclose` | FUI action object chạy sau khi đóng dialog |
+| Param     | Meaning                             |
+| --------- | ----------------------------------- |
+| `title`   | Title                               |
+| `message` | Body                                |
+| `type`    | Color: `'blue'`, `'red'`, `'green'` |
+| `icon`    | Icon class                          |
+| `onclose` | FUI action object run after close   |
 
 ```js
-showMessage({ title: 'Thông báo', message: 'Lưu thành công!' });
+showMessage({ title: "Thông báo", message: "Lưu thành công!" });
 
 showMessage({
-    title: 'Lỗi',
-    message: 'Không tìm thấy dữ liệu',
-    type: 'red',
-    icon: 'mdi mdi-alert-circle'
+  title: "Lỗi",
+  message: "Không tìm thấy dữ liệu",
+  type: "red",
+  icon: "mdi mdi-alert-circle",
 });
 
 // Chạy action sau khi đóng
 showMessage({
-    title: 'Hoàn tất',
-    message: 'Import xong!',
-    onclose: vueData.actReload
+  title: "Hoàn tất",
+  message: "Import xong!",
+  onclose: vueData.actReload,
 });
 ```
 
@@ -81,57 +81,57 @@ showMessage({
 
 ### pushRouter(router)
 
-Cập nhật URL trên thanh địa chỉ trình duyệt (không reload trang). Dùng để đồng bộ URL với trạng thái UI hiện tại.
+Updates the browser URL without reload — sync URL with UI state.
 
 ```js
-pushRouter('/fp/don-hang/danh-sach');
+pushRouter("/fp/don-hang/danh-sach");
 ```
 
 ---
 
 ### openWindow(obj)
 
-Mở một cửa sổ FUI (`f-window`) overlay trên trang hiện tại.
+Opens an FUI window (`f-window`) overlay.
 
-| Param | Mô tả |
-|---|---|
-| `url` | URL nội dung cửa sổ (bắt buộc) |
-| `title` | Tiêu đề cửa sổ |
-| `id` | ID định danh (tự sinh nếu bỏ qua) — dùng để tránh mở trùng |
-| `width` | Chiều rộng (px hoặc %) |
-| `height` | Chiều cao |
+| Param    | Meaning                                                   |
+| -------- | --------------------------------------------------------- |
+| `url`    | Content URL (required)                                    |
+| `title`  | Window title                                              |
+| `id`     | Identifier (auto if omitted) — prevents duplicate windows |
+| `width`  | Width (px or %)                                           |
+| `height` | Height                                                    |
 
 ```js
 // Cách đơn giản — chỉ truyền URL
-openWindow('/fp/san-pham/chi-tiet?id=123');
+openWindow("/fp/san-pham/chi-tiet?id=123");
 
 // Đầy đủ options
 openWindow({
-    id: 'winChiTiet',
-    url: '/fp/san-pham/chi-tiet?id=' + vueData.selectedId,
-    title: 'Chi tiết sản phẩm',
-    width: '80%'
+  id: "winChiTiet",
+  url: "/fp/san-pham/chi-tiet?id=" + vueData.selectedId,
+  title: "Chi tiết sản phẩm",
+  width: "80%",
 });
 ```
 
-> Nếu gọi từ bên trong một `f-window` (iframe), FUI tự động chuyển sang `windowSendMessage('#PARENT', 'openWindow', obj)` để mở ở cửa sổ cha.
+> Called inside an `f-window` (iframe) → FUI switches to `windowSendMessage('#PARENT', 'openWindow', obj)` to open in the parent.
 
 ---
 
 ### redirect(obj, query)
 
-Chuyển hướng trang hiện tại sang URL khác.
+Navigates the current page to another URL.
 
 ```js
-redirect('/fp/trang-chu');
-redirect({ url: '/fp/don-hang', query: true }); // giữ lại query params hiện tại
+redirect("/fp/trang-chu");
+redirect({ url: "/fp/don-hang", query: true }); // giữ lại query params hiện tại
 ```
 
 ---
 
 ### reload()
 
-Tải lại trang hiện tại.
+Reloads the page.
 
 ```js
 reload();
@@ -141,20 +141,20 @@ reload();
 
 ### windowSendMessage(window, cmd, data)
 
-Gửi `postMessage` đến một cửa sổ/iframe khác. Dùng để giao tiếp giữa các `f-window`.
+`postMessage` to another window/iframe — communication between `f-window`s.
 
-| Param | Mô tả |
-|---|---|
-| `window` | Object window, `'#PARENT'` (cửa sổ cha), hoặc `'#iframeId'` (ID của iframe) |
-| `cmd` | Tên lệnh |
-| `data` | Dữ liệu gửi kèm |
+| Param    | Meaning                                                           |
+| -------- | ----------------------------------------------------------------- |
+| `window` | Window object, `'#PARENT'` (parent), or `'#iframeId'` (iframe ID) |
+| `cmd`    | Command name                                                      |
+| `data`   | Payload                                                           |
 
 ```js
 // Gửi lên cửa sổ cha
-windowSendMessage('#PARENT', 'refreshData', { id: vueData.selectedId });
+windowSendMessage("#PARENT", "refreshData", { id: vueData.selectedId });
 
 // Gửi đến iframe có id="iframeChild"
-windowSendMessage('#iframeChild', 'loadItem', { itemId: 5 });
+windowSendMessage("#iframeChild", "loadItem", { itemId: 5 });
 ```
 
 ---
@@ -163,89 +163,128 @@ windowSendMessage('#iframeChild', 'loadItem', { itemId: 5 });
 
 ### ajaxCALL(URL, DATA, callBack, errorCallBack, header)
 
-Gọi API bằng AJAX POST. URL chỉ cần truyền path — hệ thống tự ghép domain qua `fixURL`.
+AJAX POST. Pass only the path — domain is added via `fixURL`.
 
 ```js
-ajaxCALL('/SP_GetDonHang', { maKH: vueData.maKH }, function(res) {
-    vueData.danhSach = res.data;
+ajaxCALL("/SP_GetDonHang", { maKH: vueData.maKH }, function (res) {
+  vueData.danhSach = res.data;
 });
 
 // Với error handler
-ajaxCALL('/SP_SaveDonHang', vueData.form,
-    function(res) { Vue.$toast.success('Lưu thành công', { position: 'top' }); },
-    function(err) { showMessage({ title: 'Lỗi', message: err.message, type: 'red' }); }
+ajaxCALL(
+  "/SP_SaveDonHang",
+  vueData.form,
+  function (res) {
+    Vue.$toast.success("Lưu thành công", { position: "top" });
+  },
+  function (err) {
+    showMessage({ title: "Lỗi", message: err.message, type: "red" });
+  },
 );
 ```
 
 ---
 
-## Xuất file
+## File Export
 
 ### jsonToExcel(Obj)
 
-Xuất dữ liệu JSON ra file `.xlsx`. Tự động load ExcelJS nếu chưa có.
+Exports JSON to `.xlsx`. Auto-loads ExcelJS.
 
 **Single sheet:**
+
 ```js
 jsonToExcel({
-    data: vueData.danhSach,       // Array of objects
-    filename: 'danh-sach.xlsx',
-    worksheet: 'DanhSach'
+  data: vueData.danhSach, // Array of objects
+  filename: "danh-sach.xlsx",
+  worksheet: "DanhSach",
 });
 ```
 
 **Multi sheet:**
+
 ```js
 jsonToExcel({
-    filename: 'bao-cao.xlsx',
-    sheets: [
-        { name: 'Sheet1', data: vueData.list1 },
-        { name: 'Sheet2', data: vueData.list2 }
-    ]
+  filename: "bao-cao.xlsx",
+  sheets: [
+    { name: "Sheet1", data: vueData.list1 },
+    { name: "Sheet2", data: vueData.list2 },
+  ],
 });
 ```
 
+Without `columns`, the columns are the keys of the **first row**, headers are the key names, values are raw. A field missing from the first row is missing from the whole file.
+
+**Pick columns, headers and formats — `columns`** (`f-table excel="UI"` also uses `columns`, but only `header`/`key`, no formatting):
+
+```js
+jsonToExcel({
+  data: vueData.dsHang, // the original array of objects — no need to map each row
+  filename: "kho.xlsx",
+  worksheet: "Kho",
+  columns: [
+    { header: "Tên hàng", key: "Ten" },
+    { header: "Số lượng", key: "SoLuong", type: "number", numFmt: "#,##0", sum: true },
+    { header: "Thành tiền", key: "ThanhTien", type: "number", numFmt: "#,##0.00", sum: "#,##0" },
+    { header: "Ngày nhập", key: "NgayNhap", type: "date", numFmt: "dd/mm/yyyy" },
+    { header: "Ghi chú", key: "GhiChuHtml", type: "html", width: 40 },
+  ],
+});
+```
+
+| Field    | Meaning                                                                                                                                                                                                        |
+| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `header` | Column title. May repeat (two "Tổng" columns do not overwrite each other)                                                                                                                                      |
+| `key`    | Row field; nested paths `a.b` are supported                                                                                                                                                                    |
+| `type`   | `'number'`: numeric string → number. `'date'`: ISO/`yyyy-mm-dd` string → real date in **local time** (no one-day shift from UTC). `'html'`: strip tags, keep text. Omitted: as is (object/array → JSON string) |
+| `numFmt` | **Excel** format code (not numeral/moment): `#,##0`, `#,##0.00`, `0.0%`, `dd/mm/yyyy hh:mm`. `'#,##0;-#,##0;'` hides zeros but keeps the value                                                                 |
+| `width`  | Width in characters; omitted, it is estimated from the first 100 rows                                                                                                                                          |
+| `sum`    | `true` or a numFmt → adds a total row at the end of the sheet with a `SUM` formula over the exported rows                                                                                                      |
+
+- With `columns`, the header row is bold and frozen. Each sheet in `sheets` can have its own `columns`: `{ name, data, columns }`.
+- Only fields listed in `columns` go into the file. This is the clean export (no IDs or technical fields leak) and it is lighter than mapping to a new array of objects just to rename keys.
+
 ---
 
 ## Data Utilities
 
 ### groupBy(arrayObj, groupField, sumArr)
 
-Group mảng object theo một field và tính tổng các cột số. Trả về mảng đã group kèm `count`.
+Groups objects by a field and sums numeric columns; returns grouped array with `count`.
 
 ```js
 // groupBy(data, 'Khoa', ['SLNghiHoc', 'SLTotNghiep'])
-var result = groupBy(vueData.data, 'phongBan', ['soLuong', 'doanhThu']);
+var result = groupBy(vueData.data, "phongBan", ["soLuong", "doanhThu"]);
 // result: [{ phongBan: 'A', soLuong: 10, doanhThu: 5000, count: 3 }, ...]
 ```
 
-> Với nhu cầu group phức tạp hơn, dùng `_.groupBy` của Lodash trực tiếp.
+> For complex grouping use Lodash `_.groupBy`.
 
 ---
 
 ### findInArray(obj)
 
-Tìm phần tử trong mảng theo điều kiện.
+Finds an element by condition.
 
 ```js
 var item = findInArray({ array: vueData.list, value: { id: 5 } });
 ```
 
-> Thường dùng `_.find(array, condition)` của Lodash thay thế vì ngắn gọn hơn.
+> Usually prefer the shorter Lodash `_.find(array, condition)`.
 
 ---
 
 ### fillData(obj)
 
-Copy dữ liệu từ mảng nguồn vào object đích theo key và mapping.
+Copies data from a source array into a target object by key and mapping.
 
-- **Parameters:** `{ src, des, key, map }` — src: array nguồn, des: object đích, key: giá trị khớp, map: mapping field
+- **Parameters:** `{ src, des, key, map }` — src: source array, des: target object, key: matching value, map: field mapping
 
 ---
 
 ### buildHeader(obj, mapCol)
 
-Tự sinh mảng `headers` cho `f-table` từ dữ liệu. Không truyền `mapCol` → suy header từ key của bản ghi đầu tiên (cột số tự gán `el: 't-num'`); có `mapCol` → map từ `{ text, value }`.
+Builds `headers` for `f-table` from data. No `mapCol` → headers from the first record's keys (numeric columns get `el: 't-num'`); with `mapCol` → mapped from `{ text, value }`.
 
 ```js
 // Tự dựng header từ dữ liệu API
@@ -254,11 +293,11 @@ vueData.headers = buildHeader(vueData.dsData);
 
 ### capacityText(numb)
 
-Đổi số byte → chuỗi dung lượng (`'1.5 Mb'`, `'320 Kb'`) — dùng hiển thị kích thước file.
+Bytes → size string (`'1.5 Mb'`, `'320 Kb'`) for file sizes.
 
 ### appCommand(cmdData)
 
-Gửi lệnh sang app native (React Native / iOS webkit / Android) khi trang FUI nhúng trong app di động.
+Sends a command to the native app (React Native / iOS webkit / Android) when FUI is embedded in a mobile app.
 
 ---
 
@@ -266,13 +305,15 @@ Gửi lệnh sang app native (React Native / iOS webkit / Android) khi trang FUI
 
 ### printPDF(obj)
 
-Tạo và in/tải PDF dùng `pdfMake`. Tự động load pdfMake nếu chưa có.
+Builds and prints/downloads a PDF with `pdfMake`. Auto-loads pdfMake.
 
 ```js
 printPDF({
-    data: docDefinition,   // pdfMake docDefinition object
-    download: true,        // true = tải file, false = mở viewer
-    callBack: function() { console.log('Done'); }
+  data: docDefinition, // pdfMake docDefinition object
+  download: true, // true = tải file, false = mở viewer
+  callBack: function () {
+    console.log("Done");
+  },
 });
 ```
 
@@ -282,7 +323,7 @@ printPDF({
 
 ### copyToClipboard(textToCopy)
 
-Copy chuỗi vào clipboard. Tự động dùng `navigator.clipboard` nếu có (HTTPS), fallback về `execCommand`.
+Copies to clipboard; uses `navigator.clipboard` when available (HTTPS), else `execCommand`.
 
 ```js
 copyToClipboard(vueData.maHoaDon);
@@ -293,7 +334,7 @@ copyToClipboard(JSON.stringify(vueData.data));
 
 ### fileNameClear(fname)
 
-Xóa các ký tự đặc biệt khỏi tên file (chỉ giữ chữ, số, khoảng trắng, dấu gạch).
+Strips special characters from a file name (keeps letters, digits, spaces, dashes).
 
 ```js
 var safeName = fileNameClear(vueData.tenFile); // "report (2025)!" → "report 2025"
@@ -303,20 +344,20 @@ var safeName = fileNameClear(vueData.tenFile); // "report (2025)!" → "report 2
 
 ### hashCode(s)
 
-Tạo hash số nguyên từ chuỗi (dùng để generate key duy nhất).
+Integer hash of a string (for unique keys).
 
 ```js
-var key = hashCode('unique-string-' + Date.now());
+var key = hashCode("unique-string-" + Date.now());
 ```
 
 ---
 
 ### generateID()
 
-Tạo ID ngẫu nhiên dạng chuỗi.
+Random string ID.
 
 ```js
-var newId = 'win_' + generateID();
+var newId = "win_" + generateID();
 ```
 
 ---
@@ -325,32 +366,32 @@ var newId = 'win_' + generateID();
 
 ### getCookie(cname) / setCookie(name, value, days, domain)
 
-Đọc/ghi cookie trình duyệt.
+Read/write browser cookies.
 
 ```js
-var token = getCookie('awt');
-setCookie('theme', 'dark', 30);              // hết hạn sau 30 ngày
-setCookie('lang', 'vi', 365, '.fui.vn');    // share cookie toàn domain
+var token = getCookie("awt");
+setCookie("theme", "dark", 30); // hết hạn sau 30 ngày
+setCookie("lang", "vi", 365, ".fui.vn"); // share cookie toàn domain
 ```
 
 ---
 
 ### logout(cookiesName, domain, url)
 
-Xóa cookie và chuyển hướng đến trang login.
+Clears the cookie and redirects to login.
 
 ```js
-logout();                          // xóa cookie 'awt', redirect về login mặc định
-logout('myToken', '.fui.vn', '/login');
+logout(); // xóa cookie 'awt', redirect về login mặc định
+logout("myToken", ".fui.vn", "/login");
 ```
 
 ---
 
-## Quyền hạn
+## Permissions
 
 ### rightTest(rightObject)
 
-Kiểm tra user hiện tại có quyền hạn yêu cầu không. So sánh với `vueData.user`.
+Checks whether the current user has the required rights, against `vueData.user`.
 
 ```js
 // Kiểm tra user có role 'admin' hoặc 'manager'
@@ -368,23 +409,23 @@ if (rightTest({ dept: 'IT', level: [1, 2] })) { ... }
 
 ### colorLib(color)
 
-Utility xử lý màu sắc (hex, rgb, hsl). Dùng chủ yếu trong chart.
+Color utility (hex, rgb, hsl), mostly for charts.
 
 ```js
-var c = colorLib('#4e73df');
-c.hexString()           // '#4e73df'
-c.rgbString()           // 'rgb(78, 115, 223)'
-c.lighten(0.2)          // làm sáng 20%
-c.darken(0.1)           // làm tối 10%
-c.alpha(0.5).rgbString() // 'rgba(78, 115, 223, 0.5)'
+var c = colorLib("#4e73df");
+c.hexString(); // '#4e73df'
+c.rgbString(); // 'rgb(78, 115, 223)'
+c.lighten(0.2); // làm sáng 20%
+c.darken(0.1); // làm tối 10%
+c.alpha(0.5).rgbString(); // 'rgba(78, 115, 223, 0.5)'
 ```
 
 ### transparentize(value, opacity)
 
-Shortcut tạo màu trong suốt từ mã màu.
+Shortcut for a transparent color.
 
 ```js
-transparentize('#4e73df', 0.5)  // 'rgba(78, 115, 223, 0.5)'
+transparentize("#4e73df", 0.5); // 'rgba(78, 115, 223, 0.5)'
 ```
 
 ---
@@ -393,11 +434,11 @@ transparentize('#4e73df', 0.5)  // 'rgba(78, 115, 223, 0.5)'
 
 ### loadScripts(scriptsArray, callbackFunc)
 
-Load thêm script từ URL và chạy callback khi xong. Dùng để load thư viện on-demand.
+Loads scripts by URL, then runs the callback — on-demand libraries.
 
 ```js
-loadScripts(['/include/pdfmake/pdfmake.min.js', '/include/pdfmake/vfs_fonts.js'], function() {
-    printPDF({ data: docDef, download: true });
+loadScripts(["/include/pdfmake/pdfmake.min.js", "/include/pdfmake/vfs_fonts.js"], function () {
+  printPDF({ data: docDef, download: true });
 });
 ```
 
@@ -407,9 +448,9 @@ loadScripts(['/include/pdfmake/pdfmake.min.js', '/include/pdfmake/vfs_fonts.js']
 
 ### extractHostname(url) / getDomainWithoutSubdomain(url)
 
-Trích xuất hostname/domain từ URL. Dùng nội bộ, ít dùng trực tiếp.
+Extract hostname/domain from a URL. Internal; rarely used directly.
 
 ```js
-extractHostname('https://api.fui.vn/fp/test') // 'api.fui.vn'
-getDomainWithoutSubdomain('https://api.fui.vn') // 'fui.vn'
+extractHostname("https://api.fui.vn/fp/test"); // 'api.fui.vn'
+getDomainWithoutSubdomain("https://api.fui.vn"); // 'fui.vn'
 ```