@fui-org/fui-cli 0.1.1 → 0.3.0

package/skills/fui-skill/references/ui-crosswindow-patterns.md

@@ -0,0 +1,317 @@
+# FUI Cross-window Patterns — openWindow & data exchange
+
+> File này sở hữu: **`openWindow`, trao đổi dữ liệu giữa cửa sổ (`#PARENT`/`#Win`), `set.menu` cho module con, `onclose`**.
+
+Mở module như sub-window và trao đổi dữ liệu giữa các window/iframe (`#PARENT`, `#WinID`). Rút ra từ project **security-manager** và các ví dụ `ex-v3-*`.
+
+> Xem thêm: [ui-patterns.md](ui-patterns.md), [default-function.md](default-function.md) (`openWindow`, `windowSendMessage`).
+
+---
+
+## 1. Mở Sub-window (openWindow) — Đầy đủ
+
+Mở module khác như popup window riêng biệt. `id` là định danh để tham chiếu sau này.
+
+```json
+{
+  "FUN": "openWindow",
+  "IN": {
+    "id":     "`Win1",
+    "title":  "`User Permission",
+    "url":    "`/UserPermission",
+    "data":   "danhSachChoTable",
+    "width":  "`800px",
+    "height": "`600px",
+    "onclose": {
+      "CALL": "reloadData"
+    }
+  }
+}
+```
+
+| Param | Bắt buộc | Mô tả |
+|---|---|---|
+| `id` | ✅ | Định danh window (backtick = literal) — dùng để ref qua `#Win1` |
+| `url` | ✅ | URL module — không truyền `?menu=0`; module con tự khai báo `"set": { "menu": false }` |
+| `title` | ❌ | Tiêu đề dialog |
+| `data` | ❌ | Truyền dữ liệu vào window con — window con đọc qua `#PARENT.data` |
+| `width` / `height` | ❌ | Kích thước window (`"800px"`, `"50%"`) |
+| `onclose` | ❌ | Action chạy sau khi sub-window đóng |
+
+> **Module con mở qua openWindow:** Không truyền `?menu=0` trong URL. Module con tự khai báo `"set": { "menu": false }` trong module.json để ẩn menu vĩnh viễn cho module đó — bất kể cách mở. URL chỉ truyền ID cần thiết để query DB.
+
+**`onclose` targeting window khác:**
+
+```json
+"onclose": {
+  "#Win1": { "CALL": "cmdThongBao" }
+}
+```
+
+> Khi Win2 đóng → chạy `cmdThongBao` trong Win1 (không phải trong window hiện tại).
+
+---
+
+## 2. Cross-window Data Exchange — Đầy đủ
+
+FUI dùng `#PARENT` và `#WinID` để trao đổi dữ liệu giữa các window (iframe). Hoạt động cả same-domain và cross-domain (qua `postMessage`).
+
+### Đọc dữ liệu từ window khác (value position)
+
+```json
+"data": [
+  {
+    "sUserID":      "#PARENT.sUserID",
+    "sFullName":    "#PARENT.sFullName",
+    "dataFromWin1": "#Win1.apiChart"
+  }
+]
+```
+
+| Cú pháp | Ý nghĩa |
+|---|---|
+| `"#PARENT.field"` | Đọc `vueData.field` từ window cha |
+| `"#Win1.field"` | Đọc `vueData.field` từ iframe có id `Win1` |
+
+### Ghi dữ liệu vào window khác (key position)
+
+```json
+"data": [
+  {
+    "#PARENT.abcdef": 1234567890,
+    "#Win1.dulieuTuForm2": "`huynh cao tuan"
+  }
+]
+```
+
+```json
+":action": {
+  "#PARENT.val4": "DauRaTuCauTruc_IN"
+}
+```
+
+| Cú pháp | Ý nghĩa |
+|---|---|
+| `"#PARENT.field": value` | Ghi value vào `vueData.field` của parent |
+| `"#Win1.field": value` | Ghi value vào `vueData.field` của Win1 |
+
+### Gọi action trong window khác
+
+```json
+":action": {
+  "#PARENT": { "CALL": "cmdSETData" }
+}
+```
+
+```json
+"#Win1": { "CALL": "cmdThongBao" }
+```
+
+- `"#PARENT"` (không có field) với value là action → `runAction(value)` trong parent
+- `"#Win1"` với value là action → `runAction(value)` trong Win1
+
+### Nhận dữ liệu được truyền khi openWindow
+
+Khi window cha mở con với `"data": "sourceData"`:
+
+```json
+"data": [
+  {
+    "LayDuLieuWinCha": "#PARENT.Win1"
+  }
+]
+```
+
+> `#PARENT.Win1` đọc biến `Win1` từ parent. Khi cha gọi `openWindow` với `id: "Win1"`, FUI tự set `vueData.Win1 = data_đã_truyền` trong parent trước khi mở window.
+
+### Pattern đầy đủ — Sub-window nhận data từ parent
+
+**Module cha (ex-v3-1SetData):**
+```json
+":action": {
+  "FUN": "openWindow",
+  "IN": {
+    "id":   "`Win1",
+    "url":  "`/ex/ex-v3-2CauTruc",
+    "data": "danhSachChoTable"
+  }
+}
+```
+
+**Module con (ex-v3-2CauTruc):**
+```json
+"data": [
+  {
+    "IF": "typeof menu != 'undefined' && menu=='0'",
+    "THEN": { "v_Set.menu": false }
+  },
+  {
+    "LayDuLieuWinCha":    "#PARENT.Win1",
+    "GiaTriTuCHA.thu.xem": "#PARENT.val7",
+    "GiaTriSetTuCHA":      null
+  }
+]
+```
+
+> Đặt `#PARENT.*` TRƯỚC các CALL startup để data sẵn sàng trước khi API đầu tiên chạy.
+
+---
+
+## 3. Sub-window Checklist
+
+Module được mở qua `openWindow` cần:
+
+- `"set": { "menu": false }` — ẩn navigation header (khai báo trong module.json, không dùng `?menu=0` trong URL)
+- URL params tự động inject vào `vueData` trước khi `data[]` chạy — `{ "CALL": "apiLoad" }` ở cuối `data[]` là đủ
+- URL chỉ truyền **ID** của record cha mà module con thực sự dùng — không truyền name hay field có thể tra lại từ DB
+
+```json
+// module.json của module con
+"set": { "menu": false },
+"data": [
+  { "ContestID": null },
+  {
+    "getDetail": {
+      "API": "/SM_Contest_Detail",
+      "IN": { "ContestID": "ContestID" },
+      "OUT": "dsDetail"
+    }
+  },
+  { "CALL": "getDetail" }
+]
+// ContestID tự động inject từ URL ?ContestID=xxx trước khi data[] chạy
+```
+
+---
+
+## 4. Ví dụ hoàn chỉnh cha ↔ con (chuẩn `ex-v3-1SetData` → `ex-v3-2CauTruc`)
+
+Đây là mẫu chuẩn: **cửa sổ cha mở con qua `openWindow`, truyền dữ liệu bảng, con đọc/ghi/gọi lệnh ngược lên cha.**
+
+### 4.1 Cửa sổ CHA — f-table + nút mở con, truyền `data`
+
+`data` trong `openWindow.IN` truyền thẳng object/array (ở đây là danh sách bảng `danhSachChoTable`) sang con; con đọc qua `#PARENT.<id>`.
+
+```json
+{
+  "el": "f-table",
+  "attr": {
+    "label": "Danh sách",
+    ":items": "danhSachChoTable",
+    ":headers": [
+      { "text": "STT", "value": "STT" },
+      { "text": "Họ",  "value": "ho" },
+      { "text": "Tên", "value": "ten" }
+    ]
+  },
+  "w": "6"
+},
+{
+  "el": "f-button",
+  "attr": {
+    "label": "Open Window",
+    ":action": {
+      "FUN": "openWindow",
+      "IN": {
+        "id": "`Win1",
+        "title": "`Chỉnh sửa cho module",
+        "url": "`/ex/ex-v3-2CauTruc",
+        "data": "danhSachChoTable"
+      }
+    }
+  },
+  "w": "3"
+}
+```
+
+Cha cũng có thể khai báo **action đặt tên** để con gọi ngược lên, và ghi thẳng vào con trong `data[]`:
+
+```json
+"data": [
+  { "#PARENT.abcdef": 1234567890, "#Win1": { "CALL": "cmdTHONGBao" } },
+  {
+    "cmdSETData": [
+      { "MESS": "Lệnh của form CHA được gọi từ form CON" },
+      { "#Win1.GiaTriSetTuCHA": "Giá trị set từ CHA" }
+    ]
+  }
+]
+```
+
+### 4.2 Cửa sổ CON — đọc data cha, ghi ngược, gọi lệnh cha, mở thêm con
+
+```json
+// data[] của con: đọc dữ liệu cha NGAY đầu tiên
+"data": [
+  {
+    "LayDuLieuWinCha": "#PARENT.Win1",   // = data cha đã truyền qua openWindow (id=Win1)
+    "GiaTriTuCHA.thu.xem": "#PARENT.val7",
+    "GiaTriSetTuCHA": null
+  }
+],
+"set": { "menu": false, "login": false }
+```
+
+```json
+// Các nút trong controls của con:
+{ "el": "f-button", "attr": { "label": "Lấy dữ liệu từ cha",
+  ":action": { "USERINFO": "#PARENT.val4" } } },
+
+{ "el": "f-button", "attr": { "label": "Set dữ liệu xuống cha",
+  ":action": { "#PARENT.val4": "DauRaTuCauTruc_IN" } } },
+
+{ "el": "f-button", "attr": { "label": "Gọi lệnh ở cha",
+  ":action": { "#PARENT": { "CALL": "cmdSETData" } } } },
+
+{ "el": "f-button", "attr": { "label": "Mở thêm form con",
+  ":action": { "FUN": "openWindow", "IN": {
+    "id": "`Win2",
+    "url": "`https://fui.vn/ex/ex-v3-1SetData",
+    "onclose": { "#Win1": { "CALL": "cmdThongBaoCuaFormNay" } }
+  } } } }
+```
+
+**Tổng hợp cú pháp trao đổi (value = đọc, key = ghi):**
+
+| Cú pháp | Ý nghĩa |
+|---|---|
+| `"x": "#PARENT.field"` | Đọc `field` của cha vào `x` |
+| `"x": "#Win1.field"` | Đọc `field` của cửa sổ id `Win1` |
+| `"#PARENT.field": "src"` | Ghi `src` vào `field` của cha |
+| `"#Win1.field": "src"` | Ghi vào cửa sổ `Win1` |
+| `"#PARENT": { "CALL": "cmd" }` | Gọi action `cmd` trong cha |
+| `"#Win1": { "CALL": "cmd" }` | Gọi action trong `Win1` |
+| `openWindow.IN.data` | Truyền object/array sang con; con đọc `#PARENT.<id>` |
+| `openWindow.IN.onclose` | Action chạy sau khi con đóng (có thể nhắm `#WinX`) |
+
+> Hoạt động cả **same-domain và cross-domain** (runtime tự dùng `postMessage` khi khác tên miền).
+
+---
+
+## 5. f-table / f-sheet + mở cửa sổ chi tiết
+
+Pattern rất phổ biến: bảng danh sách → click một dòng → mở cửa sổ con để xem/sửa chi tiết dòng đó.
+
+- Trong `headers` của `f-table`, dùng `t-button` hoặc `t-menu` với `:action` gọi `openWindow`; `item` là dòng hiện tại.
+- Truyền **chỉ ID** của dòng qua URL (con tự query DB), hoặc truyền cả object dòng qua `openWindow.IN.data`.
+
+```json
+{
+  "el": "t-button", "text": "Chi tiết", "value": "ID", "align": "center",
+  "attr": {
+    "icon-text": "mdi-eye", "color": "primary",
+    ":action": {
+      "FUN": "openWindow",
+      "IN": {
+        "id": "`WinDetail",
+        "title": "`Chi tiết",
+        "url": "`/DetailModule?RecordID={{item.ID}}",
+        "onclose": { "CALL": "reloadList" }
+      }
+    }
+  }
+}
+```
+
+- **`f-sheet`** (bảng tính nhập lưới) kết hợp tương tự: nút/menu trong sheet gọi `openWindow`, hoặc lưu cả `vueData` của sheet rồi mở con để nhập bổ sung; con ghi ngược qua `#PARENT.<field>` khi đóng.
+- Reload sau khi con đóng: đặt `onclose: { "CALL": "reloadList" }` (chạy trong cửa sổ mở nó) — xem §1.

package/skills/fui-skill/references/ui-dialog-patterns.md

@@ -0,0 +1,229 @@
+# FUI Dialog Patterns — v-dialog thủ công (CHUẨN), hidden-container, checkbox-list
+
+> File này sở hữu: **dialog thủ công: `hidden-container`, anatomy `v-card`/`v-toolbar`, mở dialog kèm row, checkbox-list**. `f-dialog` xem [components-dialog.md](components-dialog.md).
+
+Các pattern dialog/form popup trong FUI. Rút ra từ **security-manager** và demo **ex-v3-dialog**.
+
+> **CHUẨN thiết kế dialog: dựng `v-dialog` thủ công theo anatomy trong mục 1** (dễ đọc/chỉnh sửa từng phần), với **diện mạo mô phỏng `f-dialog`**: toolbar `dense flat` không màu + close icon, form floating label, hàng cuối là `v-card-actions`. Hàng action căn phải, button giữ chiều ngang tự nhiên; chỉ action chính mới được tô màu nền, action phụ dùng nút text. Anatomy đầy đủ + bảng quy tắc: xem `design_read("fui")` §4–5. `f-dialog` (mục 0) là lựa chọn phụ cho form rất nhỏ.
+
+> Xem thêm: [ui-patterns.md](ui-patterns.md), [ui-table-cell-patterns.md](ui-table-cell-patterns.md) (menuChucNang mở dialog), [components-dialog.md](components-dialog.md).
+
+---
+
+## 0. `f-dialog` — component dialog gọn (lựa chọn phụ)
+
+`f-dialog` gói sẵn card + toolbar + nút — ngắn hơn so với dựng `v-dialog` thủ công, nhưng khó tùy biến layout. Chỉ dùng cho form rất nhỏ/đơn giản; mặc định vẫn là `v-dialog` thủ công (mục 1). Các field bên trong dùng `v-model` **trỏ thẳng tới key của object `data`** (không cần `vueData.dialogData.X`).
+
+```json
+{
+  "el": "f-dialog",
+  "attr": {
+    "v-model": "dialogOpen",            // boolean mở/đóng
+    "v-model:data": "dialogData",       // object dữ liệu của form
+    "title": "Nhập dữ liệu",
+    ":open-action": { "MESSBOX": "Bạn vừa mở dialog" },
+    ":controls": [
+      { "el": "v-text-field", "attr": { "v-model": "Domain",   "label": "Domain" },   "w": 4 },
+      { "el": "v-text-field", "attr": { "v-model": "ModuleID", "label": "ModuleID" }, "w": 3 },
+      { "el": "v-checkbox",   "attr": { "v-model": "checkBoxValue",
+          ":label": "`Tôi đồng ý: ${checkBoxValue}`" } },
+      { "el": "v-select", "attr": { "label": "Chọn", "v-model": "bienselect",
+          ":items": "vueData.Mang", "item-title": "AppName", "item-value": "AppListID" } }
+    ],
+    ":watch": {
+      "bienselect": { "MESSBOX": "Watch {{bienselect}}" }
+    },
+    ":button": [
+      { "label": "Lưu", "type": "submit", ":disabled": "!checkBoxValue",
+        "action": [ { "MESSBOX": "Đã lưu" }, { "dialogOpen": false } ] },
+      { "label": "Chạy API", "checkvalid": true, "v-if": "ModuleID==1",
+        "action": [ { "API": "/chaymotapi" } ] },
+      { "label": "Đóng", "action": [ { "dialogOpen": false } ] }
+    ]
+  }
+}
+```
+
+| Prop | Vai trò |
+|---|---|
+| `v-model` | Biến boolean mở/đóng dialog |
+| `v-model:data` | Object chứa dữ liệu form; field trong `:controls` bind trực tiếp tới key của nó |
+| `title` | Tiêu đề dialog |
+| `:open-action` | Action chạy khi dialog mở |
+| `:controls` | Mảng Control Object = các field của form |
+| `:watch` | Watcher phạm vi trong dialog (theo tên field) |
+| `:button` | Mảng nút: `label`, `type:"submit"`, `checkvalid`, `:disabled`, `v-if`, `action` |
+
+**Khi nào dùng gì:** mặc định mọi dialog → **`v-dialog` thủ công theo mục 1** (chuẩn project). `f-dialog` chỉ khi form rất nhỏ (1–3 field, không layout đặc biệt) và user không yêu cầu tùy biến.
+
+---
+
+## 1. Dialog Pattern — v-dialog thủ công trong hidden-container (CHUẨN)
+
+Dialogs luôn đặt trong container riêng với `prop: "hidden-container"` — không nằm trong rows chính.
+
+**Cấu trúc chuẩn:**
+
+```json
+{
+  "prop": "hidden-container",
+  "rows": [
+    {
+      "prop": "",
+      "cols": [
+        {
+          "el": "v-dialog",
+          "attr": {
+            "v-model": "dlUserInfo",
+            "width": 650
+          },
+          "innerHTML": [
+            {
+              "el": "v-card",
+              "attr": { "class": "pa-0" },
+              "innerHTML": [
+                {
+                  "el": "v-toolbar",
+                  "attr": { "dense": "", "flat": "" },
+                  "innerHTML": [
+                    { "el": "v-toolbar-title", "attr": {}, "innerHTML": "Update User Info" },
+                    { "el": "v-spacer", "attr": {} },
+                    {
+                      "el": "v-btn",
+                      "innerHTML": "<v-icon>mdi-close</v-icon>",
+                      "attr": { "icon": "", "v-on:click": "vueData.dlUserInfo = false" }
+                    }
+                  ]
+                },
+                {
+                  "el": "v-container",
+                  "attr": { "class": "grid-list-md px-4" },
+                  "innerHTML": [
+                    { "el": "v-layout", "w": 12, "attr": { "row": "", "wrap": "" }, "innerHTML": [
+                        { "el": "v-text-field", "col": {}, "attr": { "v-model": "vueData.sUserName", "label": "Tên đăng nhập" }, "w": 6 },
+                        { "el": "v-text-field", "col": {}, "attr": { "v-model": "vueData.sLastName", "label": "Họ tên" }, "w": 6 }
+                    ]}
+                  ]
+                },
+                {
+                  "el": "v-card-actions",
+                  "attr": { "class": "mr-1 mb-1" },
+                  "innerHTML": [
+                    { "el": "v-spacer", "attr": {} },
+                    {
+                      "el": "f-button",
+                      "attr": {
+                        "text": "",
+                        "label": "Đặt lại",
+                        ":action": { "CALL": "resetForm" }
+                      }
+                    },
+                    {
+                      "el": "f-button",
+                      "attr": {
+                        "color": "primary",
+                        ":checkvalid": true,
+                        "label": "Lưu",
+                        "icon-text": "mdi-content-save",
+                        ":action": {
+                          "API": "SM_Users_Update",
+                          "IN": { "UserID": "sUserID", "UserName": "sUserName" },
+                          "CALLBACK": [
+                            { "MESS": "Cập nhật thành công." },
+                            { "dlUserInfo": false },
+                            { "CALL": "getUser" }
+                          ]
+                        }
+                      }
+                    }
+                  ]
+                }
+              ]
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}
+```
+
+**Quy tắc dialog (phong cách f-dialog):**
+- `v-card[class="pa-0"]` — triệt đệm để toolbar tràn sát mép (ưu tiên class Vuetify, không inline style); không elevation/outlined
+- `v-toolbar[dense flat]` — thanh tiêu đề mỏng, **không** color/dark
+- Nút đóng: `v-btn[icon]` mdi-close + `v-on:click: "vueData.dlXxx = false"` — không thêm nút "Đóng" ở actions
+- Thân form: `v-container.grid-list-md.px-4` > `v-layout[row wrap]` > field **floating label** (`label` trong attr, w:12 dài / 6+6 ngắn) — KHÔNG dùng label div rời
+- Hàng cuối chứa nút phải là `v-card-actions[class="mr-1 mb-1"]`, không đặt nhóm action trong một `v-layout`, `v-container` hay row form thông thường
+- `v-spacer` đứng trước nhóm nút → toàn bộ action căn phải
+- Button giữ chiều ngang tự nhiên theo nội dung: không đặt `w`, `width`, `block`, `flex-grow` hoặc bọc mỗi nút trong cột giãn
+- Tối đa một action quan trọng nhất (ví dụ **Lưu**) được dùng nền `color="primary"`; action phụ/ít quan trọng dùng `f-button` + `"text": ""`, không tô nền. Giữ số nút ít, nhãn ngắn và trình bày nhã nhặn
+- CALLBACK của Save: MESS → đóng dialog → reload data
+
+---
+
+## 2. Mở Dialog với Dữ Liệu Row
+
+Pattern 2 bước: copy dữ liệu vào state → set `dlXxx = true`.
+
+**Từ menuChucNang:**
+```json
+"action": [
+  {
+    "addNew": 0,
+    "dongChon": "item",
+    "sUserID":    "item.UserID",
+    "sUserName":  "item.UserName",
+    "sLastName":  "item.LastName"
+  },
+  { "dlUserInfo": true }
+]
+```
+
+**Từ f-button:**
+```json
+":action": [
+  { "addNew": 1, "sUserID": "", "sUserName": "" },
+  { "dlUserInfo": true }
+]
+```
+
+> `addNew: 0` = edit mode, `addNew: 1` = new mode. Trong dialog, dùng `:disabled="addNew==0"` để khóa field ID khi edit.
+
+---
+
+## 3. Checkbox List Dialog Pattern
+
+Dialog chứa danh sách checkbox để chọn nhiều items, lưu ngay khi click.
+
+```json
+{
+  "el": "v-card-text",
+  "attr": {},
+  "innerHTML": [
+    {
+      "el": "v-layout",
+      "attr": { "class": "fluid row justify-center grid-list-lg fill-height mt-3" },
+      "innerHTML": [
+        {
+          "el": "div",
+          "attr": { "v-for": "fc in vueData.dsFunctionRight", ":key": "fc.FunctionID" },
+          "innerHTML": [
+            {
+              "el": "v-checkbox",
+              "attr": {
+                "color": "primary",
+                "v-model": "sFunctionSelected",
+                ":value": "`${fc.FunctionID}`",
+                ":label": "`${fc.FunctionName}`",
+                "v-on:click": "CALL(saveFunction)"
+              }
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}
+```
+
+> `v-on:click` trên checkbox → save ngay không cần nút Save. `v-model` nhận array, `:value` dùng backtick literal.