@fui-org/fui-cli 2.1.4 → 2.2.0

package/skills/{fui-skill → fui}/references/module-data-patterns.md

@@ -1,117 +1,117 @@
-# module.json `data[]` — State declaration & value resolution
-
-> Owns: **`data[]` declaration patterns: three element kinds, order state → named action → auto-startup**. Value resolution: [controls-patterns.md](controls-patterns.md) §0; nested key syntax (dot/bracket/`#PARENT`): [controls-patterns.md](controls-patterns.md) §1; cross-window: [ui-crosswindow-patterns.md](ui-crosswindow-patterns.md).
-
-FUI processes `data[]` **sequentially top to bottom**; each object assigns/runs based on how its value is written. Examples come from `ex/ex-v3-1SetData` + `ex-v3-2CauTruc` (official FUI demo modules).
-
-> Overview of the 4 blocks: [module-json-anatomy.md](module-json-anatomy.md). Engine: [platform-architecture.md](platform-architecture.md) §5.
-
----
-
-## 1. Three element kinds in `data[]`
-
-```json
-"data": [
-  { "keyword": "", "dsUser": [], "dlOpen": false },          // (a) khởi tạo state
-  { "getUser": { "API": "...", "IN": {...}, "OUT": "dsUser" } }, // (b) named action
-  { "API": "...", "OUT": "dsInit" },                          // (c) action tự chạy khi load
-  { "CALL": "getUser" }                                        // (c) auto-startup
-]
-```
-
-- (a) no action key → creates reactive var in `vueData`.
-- (b) key is a **function name** → reusable action (invoke via `CALL`).
-- (c) object is itself an action (`API`/`CALL`/`FUN`…) → **runs on page load**, in order.
-
----
-
-## 2. Value resolution — HOW you write it decides the VALUE (common mistake)
-
-Full rules (`getVueData`: backtick / `{{ }}` / string with spaces / string without spaces → JS eval) live in [controls-patterns.md §0](controls-patterns.md#0-value-resolution-rules-fundamental) — Tier A, always loaded; not repeated here.
-
-> **Consequence for `data[]`:** to assign a **fixed string without spaces** (id, url, code) → **wrap in backticks** (``"`winUser"``) or single quotes (`"'winUser'"`), otherwise FUI treats it as a variable. This is the most common `data`/`IN` bug.
-
----
-
-## 3. Keys as nested paths (deep set)
-
-The left-hand key is also resolved (dot / bracket / dynamic index / `#PARENT`) — full syntax in [controls-patterns.md §1](controls-patterns.md#1-data-keys-and-assignment) _(Tier A, already loaded)_.
-
----
-
-## 4. Auto-run action: inline `IN`/`OUT`/`API` on load
-
-A standalone action object in `data[]` runs on load; no name needed:
-
-```json
-{ "API": "https://tapi.example.vn/me/auth/ApplicationList", "OUT": "Mang" },
-{ "IN": { "ABC": "`gdsgdsg", "DEF": "val5", "CBV": 1233 }, "OUT": "DoiTuong" }
-```
-
-→ loads the page's initial data (catalogs, dropdowns, table data).
-
----
-
-## 5. Named action + CALLBACK (reusable)
-
-```json
-{
-  "cmdSETData": [{ "MESS": "Thông báo" }, { "#Win1.GiaTriSetTuCHA": "Giá trị set từ CHA" }],
-  "apiChart": {
-    "API": "/ts/TS_Report_ForChart/{{ab}}",
-    "IN": { "sachID": "apiLoadFBUser", "modeY": 12345 },
-    "OUT": "DSDoiQuaTang",
-    "CALLBACK": { "AAA": "val2" }
-  }
-}
-```
-
-Invoke with `{ "CALL": "cmdSETData" }` from `controls`, `watch` or another action. `CALLBACK` runs after the API completes (see [ui-patterns.md](ui-patterns.md) §7).
-
----
-
-## 6. `watch` with `v_old` — previous value
-
-In `watch`, `v_old.<field>` gives the value **before the change**:
-
-```json
-"watch": {
-  "val4": {
-    "API": "ts/auth/QuanHuyen_Select",
-    "IN": { "MaTinhTP": "tinhID" },
-    "OUT": "DS_QUAN_HUYEN",
-    "CALLBACK": { "BAC": "v_old.abcdeID" }
-  },
-  "taoID": { "dungthu": "v_old.taoID" }
-}
-```
-
-`v_old`, `deep-watch` details: [watcher-patterns.md](watcher-patterns.md).
-
----
-
-## 7. Cross-window exchange inside `data[]`
-
-`data[]` can read/write other windows via `#PARENT.*` / `#WinID.*` keys/values — place **before** fetch CALLs:
-
-```json
-"data": [
-  {
-    "LayDuLieuWinCha": "#PARENT.Win1",   // đọc data cha
-    "#PARENT.abcdef": 1234567890,        // ghi xuống cha
-    "#Win1": { "CALL": "cmdTHONGBao" }   // gọi lệnh ở Win1
-  }
-]
-```
-
-Full: [ui-crosswindow-patterns.md](ui-crosswindow-patterns.md).
-
----
-
-## 8. `data[]` checklist
-
-1. Initialize **every** state var in the first object (including `[]`, `false`, `null`) so reactivity works.
-2. Named actions in the middle; auto-startup (`CALL`/`API`) **last**.
-3. Fixed space-free strings → **backticks**; never let FUI read them as variables.
-4. `#PARENT.*` / URL vars before fetch CALLs.
-5. No complex logic in `data` — move to `script.js` (functions) or sparing `EXE`.
+# module.json `data[]` — State declaration & value resolution
+
+> Owns: **`data[]` declaration patterns: three element kinds, order state → named action → auto-startup**. Value resolution: [controls-patterns.md](controls-patterns.md) §0; nested key syntax (dot/bracket/`#PARENT`): [controls-patterns.md](controls-patterns.md) §1; cross-window: [ui-crosswindow-patterns.md](ui-crosswindow-patterns.md).
+
+FUI processes `data[]` **sequentially top to bottom**; each object assigns/runs based on how its value is written. Examples come from `ex/ex-v3-1SetData` + `ex-v3-2CauTruc` (official FUI demo modules).
+
+> Overview of the 4 blocks: [module-json-anatomy.md](module-json-anatomy.md). Engine: [platform-architecture.md](platform-architecture.md) §5.
+
+---
+
+## 1. Three element kinds in `data[]`
+
+```json
+"data": [
+  { "keyword": "", "dsUser": [], "dlOpen": false },          // (a) khởi tạo state
+  { "getUser": { "API": "...", "IN": {...}, "OUT": "dsUser" } }, // (b) named action
+  { "API": "...", "OUT": "dsInit" },                          // (c) action tự chạy khi load
+  { "CALL": "getUser" }                                        // (c) auto-startup
+]
+```
+
+- (a) no action key → creates reactive var in `vueData`.
+- (b) key is a **function name** → reusable action (invoke via `CALL`).
+- (c) object is itself an action (`API`/`CALL`/`FUN`…) → **runs on page load**, in order.
+
+---
+
+## 2. Value resolution — HOW you write it decides the VALUE (common mistake)
+
+Full rules (`getVueData`: backtick / `{{ }}` / string with spaces / string without spaces → JS eval) live in [controls-patterns.md §0](controls-patterns.md#0-value-resolution-rules-fundamental) — Tier A, always loaded; not repeated here.
+
+> **Consequence for `data[]`:** to assign a **fixed string without spaces** (id, url, code) → **wrap in backticks** (``"`winUser"``) or single quotes (`"'winUser'"`), otherwise FUI treats it as a variable. This is the most common `data`/`IN` bug.
+
+---
+
+## 3. Keys as nested paths (deep set)
+
+The left-hand key is also resolved (dot / bracket / dynamic index / `#PARENT`) — full syntax in [controls-patterns.md §1](controls-patterns.md#1-data-keys-and-assignment) _(Tier A, already loaded)_.
+
+---
+
+## 4. Auto-run action: inline `IN`/`OUT`/`API` on load
+
+A standalone action object in `data[]` runs on load; no name needed:
+
+```json
+{ "API": "https://tapi.example.vn/me/auth/ApplicationList", "OUT": "Mang" },
+{ "IN": { "ABC": "`gdsgdsg", "DEF": "val5", "CBV": 1233 }, "OUT": "DoiTuong" }
+```
+
+→ loads the page's initial data (catalogs, dropdowns, table data).
+
+---
+
+## 5. Named action + CALLBACK (reusable)
+
+```json
+{
+  "cmdSETData": [{ "MESS": "Thông báo" }, { "#Win1.GiaTriSetTuCHA": "Giá trị set từ CHA" }],
+  "apiChart": {
+    "API": "/ts/TS_Report_ForChart/{{ab}}",
+    "IN": { "sachID": "apiLoadFBUser", "modeY": 12345 },
+    "OUT": "DSDoiQuaTang",
+    "CALLBACK": { "AAA": "val2" }
+  }
+}
+```
+
+Invoke with `{ "CALL": "cmdSETData" }` from `controls`, `watch` or another action. `CALLBACK` runs after the API completes (see [ui-patterns.md](ui-patterns.md) §7).
+
+---
+
+## 6. `watch` with `v_old` — previous value
+
+In `watch`, `v_old.<field>` gives the value **before the change**:
+
+```json
+"watch": {
+  "val4": {
+    "API": "ts/auth/QuanHuyen_Select",
+    "IN": { "MaTinhTP": "tinhID" },
+    "OUT": "DS_QUAN_HUYEN",
+    "CALLBACK": { "BAC": "v_old.abcdeID" }
+  },
+  "taoID": { "dungthu": "v_old.taoID" }
+}
+```
+
+`v_old`, `deep-watch` details: [watcher-patterns.md](watcher-patterns.md).
+
+---
+
+## 7. Cross-window exchange inside `data[]`
+
+`data[]` can read/write other windows via `#PARENT.*` / `#WinID.*` keys/values — place **before** fetch CALLs:
+
+```json
+"data": [
+  {
+    "LayDuLieuWinCha": "#PARENT.Win1",   // đọc data cha
+    "#PARENT.abcdef": 1234567890,        // ghi xuống cha
+    "#Win1": { "CALL": "cmdTHONGBao" }   // gọi lệnh ở Win1
+  }
+]
+```
+
+Full: [ui-crosswindow-patterns.md](ui-crosswindow-patterns.md).
+
+---
+
+## 8. `data[]` checklist
+
+1. Initialize **every** state var in the first object (including `[]`, `false`, `null`) so reactivity works.
+2. Named actions in the middle; auto-startup (`CALL`/`API`) **last**.
+3. Fixed space-free strings → **backticks**; never let FUI read them as variables.
+4. `#PARENT.*` / URL vars before fetch CALLs.
+5. No complex logic in `data` — move to `script.js` (functions) or sparing `EXE`.

package/skills/{fui-skill → fui}/references/module-json-anatomy.md

@@ -1,132 +1,132 @@
-# module.json Anatomy — data · watch · controls · set
-
-> Owns: **the 4 `module.json` blocks (data/watch/controls/set) — roles, interaction, structure checklist**. Action/control syntax: [controls-patterns.md](controls-patterns.md).
-
-`module.json` describes one FUI page with exactly **4 top-level blocks**. Runtime internals: [platform-architecture.md](platform-architecture.md). Battle-tested UI patterns (high priority): [ui-patterns.md](ui-patterns.md).
-
-```json
-{
-  "data": [/* state + action */],
-  "watch": {/* observer → action */},
-  "controls": [/* layout UI: container > rows > cols */],
-  "set": {/* override config trang (tùy chọn) */}
-}
-```
-
-Runtime order: `runAction(data)` → `buildModuleUI(controls)` → attach `watch` → merge `set` into page config. All state lives in `vueData`.
-
----
-
-## 1. `data` — state init + action definitions
-
-An **array**, processed top to bottom on page load. Three element kinds:
-
-| Object kind  | Recognized by                                    | Effect                              |
-| ------------ | ------------------------------------------------ | ----------------------------------- |
-| State init   | No action key (`API`/`CALL`/`IF`...)             | Creates reactive var in `vueData`   |
-| Named action | Key = function name, value = action object       | Reusable action (invoke via `CALL`) |
-| Auto-startup | Standalone `{ "API": ... }` or `{ "CALL": ... }` | **Runs immediately** on load        |
-
-```json
-"data": [
-  { "dsUser": [], "sGroup": null, "dlUserInfo": false },
-  {
-    "getUser": { "API": "SM_Users_SelectByDepGroup", "IN": { "GroupID": "sGroup" }, "OUT": "dsUser" }
-  },
-  { "CALL": "getUser" }
-]
-```
-
-Named actions are callable from `watch`, `controls` or other actions; trailing auto-startup = initial page data.
-
-Details: `data[]` declaration + value resolution (string/var/backtick/`{{ }}`/deep key, auto-run, named action, `v_old`) → **[module-data-patterns.md](module-data-patterns.md)**; action engine → [controls-patterns.md](controls-patterns.md); real-world data layout → [ui-patterns.md](ui-patterns.md) §1–2.
-
----
-
-## 2. `watch` — state change → run action
-
-An **object** `{ "varName": action }`; action runs when the var changes.
-
-```json
-"watch": {
-  "sGroup":      { "CALL": "getUser" },
-  "sDepartment": { "CALL": "getUser" },
-  "sModuleID":   [ { "CALL": "getSysRight" }, { "CALL": "getFunctionRight" } ]
-}
-```
-
-- **Cascading filter**: one watch per filter dropdown → table reloads on change.
-- Multiple actions for one var → use an **array**.
-- **`deep-watch`**: tracks nested changes inside object/array (runtime supports the `deep-watch` key).
-
-Details: [watcher-patterns.md](watcher-patterns.md) (v_old, deep-watch, cascading), [ui-patterns.md](ui-patterns.md) §3.
-
----
-
-## 3. `controls` — UI layout (mandatory grid container > rows > cols)
-
-An **array** of containers. Runtime builds `container (v-container)` → `rows (v-layout)` → `cols` → each item is a **Control Object**.
-
-```json
-"controls": [
-  {
-    "prop": "fluid grid-list-md",
-    "rows": [
-      { "prop": "row", "cols": [ /* Control Objects */ ] }
-    ]
-  }
-]
-```
-
-Control Object keys:
-
-| Key         | Role                                                                                                                                   |
-| ----------- | -------------------------------------------------------------------------------------------------------------------------------------- |
-| `el`        | Tag/component: `div`, `v-*` (Vuetify), `f-*`/`t-*` (FUI), `uc-*` (custom)                                                              |
-| `attr`      | Attributes/directives (`class`, `style`, `v-model`, `v-on:click`) — **use `v-on:click`, NOT `@click`**                                 |
-| `w`         | Column width: `1–12` (grid) or `>= 25` (px, **requires `col: { "class": "shrink" }`**). Never 13–24. Required for every item in `cols` |
-| `col`       | Wrapping grid column config (`class`, `style`, `v-if`)                                                                                 |
-| `innerHTML` | Content: string (supports `{{ }}`) or array of nested Control Objects                                                                  |
-
-Mandatory: always start with the grid wrapper; nest via `innerHTML` (array), never `children`; put dialogs in a container with `prop: "hidden-container"`.
-
-Details: structure & grid → [controls-patterns.md](controls-patterns.md) §6; **allowed class/prop/style (don't invent styles)** → [controls-styling-vocabulary.md](controls-styling-vocabulary.md); picking components → [component-quickref.md](component-quickref.md); layout/table/dialog patterns → [ui-patterns.md](ui-patterns.md), [ui-table-cell-patterns.md](ui-table-cell-patterns.md), [ui-dialog-patterns.md](ui-dialog-patterns.md), [ui-layout-patterns.md](ui-layout-patterns.md).
-
----
-
-## 4. `set` — per-page config override (optional)
-
-An **object** overriding project config for this page. Runtime merges `project.json` then `set` (module wins) — see [platform-architecture.md](platform-architecture.md) §2.1.
-
-```json
-"set": {
-  "title": "Quản lý sinh viên",
-  "menu": false
-}
-```
-
-Declare only fields differing from the project. Common: `title`, `menu: false` (hide header — sub-window/landing), `menuLeft` (own sidebar), `apiDomain` (different backend for this page). Normal pages **need no `set`**.
-
-Full property list: [project-config.md](project-config.md).
-
----
-
-## How the 4 blocks interact
-
-```
-URL ?param  ──►  vueData[param]         (inject trước khi data chạy)
-data[]      ──►  tạo state + action, auto-startup fetch
-controls    ──►  bind hai chiều vào state (v-model), gọi action (:action / v-on)
-watch       ──►  state đổi → chạy action → cập nhật state khác → UI re-render
-set         ──►  quyết định khung trang (title/menu/apiDomain) bao quanh controls
-```
-
-Typical loop: user acts on `controls` → state changes → `watch` fires → `API` action in `data` → `OUT` updates state → `controls` re-render.
-
-## Checklist
-
-1. `data[]`: state first → named actions → `{ "CALL": ... }` auto-startup last
-2. `watch`: every filter/dropdown has a watch → reload
-3. `controls`: start with grid wrapper; `w` on every item; dialogs in `hidden-container`; `v-on:click` not `@click`
-4. `set`: only when the page differs from project defaults
-5. Reference state as `vueData.` in controls/attr; valid JSON (no trailing commas)
+# module.json Anatomy — data · watch · controls · set
+
+> Owns: **the 4 `module.json` blocks (data/watch/controls/set) — roles, interaction, structure checklist**. Action/control syntax: [controls-patterns.md](controls-patterns.md).
+
+`module.json` describes one FUI page with exactly **4 top-level blocks**. Runtime internals: [platform-architecture.md](platform-architecture.md). Battle-tested UI patterns (high priority): [ui-patterns.md](ui-patterns.md).
+
+```json
+{
+  "data": [/* state + action */],
+  "watch": {/* observer → action */},
+  "controls": [/* layout UI: container > rows > cols */],
+  "set": {/* override config trang (tùy chọn) */}
+}
+```
+
+Runtime order: `runAction(data)` → `buildModuleUI(controls)` → attach `watch` → merge `set` into page config. All state lives in `vueData`.
+
+---
+
+## 1. `data` — state init + action definitions
+
+An **array**, processed top to bottom on page load. Three element kinds:
+
+| Object kind  | Recognized by                                    | Effect                              |
+| ------------ | ------------------------------------------------ | ----------------------------------- |
+| State init   | No action key (`API`/`CALL`/`IF`...)             | Creates reactive var in `vueData`   |
+| Named action | Key = function name, value = action object       | Reusable action (invoke via `CALL`) |
+| Auto-startup | Standalone `{ "API": ... }` or `{ "CALL": ... }` | **Runs immediately** on load        |
+
+```json
+"data": [
+  { "dsUser": [], "sGroup": null, "dlUserInfo": false },
+  {
+    "getUser": { "API": "SM_Users_SelectByDepGroup", "IN": { "GroupID": "sGroup" }, "OUT": "dsUser" }
+  },
+  { "CALL": "getUser" }
+]
+```
+
+Named actions are callable from `watch`, `controls` or other actions; trailing auto-startup = initial page data.
+
+Details: `data[]` declaration + value resolution (string/var/backtick/`{{ }}`/deep key, auto-run, named action, `v_old`) → **[module-data-patterns.md](module-data-patterns.md)**; action engine → [controls-patterns.md](controls-patterns.md); real-world data layout → [ui-patterns.md](ui-patterns.md) §1–2.
+
+---
+
+## 2. `watch` — state change → run action
+
+An **object** `{ "varName": action }`; action runs when the var changes.
+
+```json
+"watch": {
+  "sGroup":      { "CALL": "getUser" },
+  "sDepartment": { "CALL": "getUser" },
+  "sModuleID":   [ { "CALL": "getSysRight" }, { "CALL": "getFunctionRight" } ]
+}
+```
+
+- **Cascading filter**: one watch per filter dropdown → table reloads on change.
+- Multiple actions for one var → use an **array**.
+- **`deep-watch`**: tracks nested changes inside object/array (runtime supports the `deep-watch` key).
+
+Details: [watcher-patterns.md](watcher-patterns.md) (v_old, deep-watch, cascading), [ui-patterns.md](ui-patterns.md) §3.
+
+---
+
+## 3. `controls` — UI layout (mandatory grid container > rows > cols)
+
+An **array** of containers. Runtime builds `container (v-container)` → `rows (v-layout)` → `cols` → each item is a **Control Object**.
+
+```json
+"controls": [
+  {
+    "prop": "fluid grid-list-md",
+    "rows": [
+      { "prop": "row", "cols": [ /* Control Objects */ ] }
+    ]
+  }
+]
+```
+
+Control Object keys:
+
+| Key         | Role                                                                                                                                   |
+| ----------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `el`        | Tag/component: `div`, `v-*` (Vuetify), `f-*`/`t-*` (FUI), `uc-*` (custom)                                                              |
+| `attr`      | Attributes/directives (`class`, `style`, `v-model`, `v-on:click`) — **use `v-on:click`, NOT `@click`**                                 |
+| `w`         | Column width: `1–12` (grid) or `>= 25` (px, **requires `col: { "class": "shrink" }`**). Never 13–24. Required for every item in `cols` |
+| `col`       | Wrapping grid column config (`class`, `style`, `v-if`)                                                                                 |
+| `innerHTML` | Content: string (supports `{{ }}`) or array of nested Control Objects                                                                  |
+
+Mandatory: always start with the grid wrapper; nest via `innerHTML` (array), never `children`; put dialogs in a container with `prop: "hidden-container"`.
+
+Details: structure & grid → [controls-patterns.md](controls-patterns.md) §6; **allowed class/prop/style (don't invent styles)** → [controls-styling-vocabulary.md](controls-styling-vocabulary.md); picking components → [component-quickref.md](component-quickref.md); layout/table/dialog patterns → [ui-patterns.md](ui-patterns.md), [ui-table-cell-patterns.md](ui-table-cell-patterns.md), [ui-dialog-patterns.md](ui-dialog-patterns.md), [ui-layout-patterns.md](ui-layout-patterns.md).
+
+---
+
+## 4. `set` — per-page config override (optional)
+
+An **object** overriding project config for this page. Runtime merges `project.json` then `set` (module wins) — see [platform-architecture.md](platform-architecture.md) §2.1.
+
+```json
+"set": {
+  "title": "Quản lý sinh viên",
+  "menu": false
+}
+```
+
+Declare only fields differing from the project. Common: `title`, `menu: false` (hide header — sub-window/landing), `menuLeft` (own sidebar), `apiDomain` (different backend for this page). Normal pages **need no `set`**.
+
+Full property list: [project-config.md](project-config.md).
+
+---
+
+## How the 4 blocks interact
+
+```
+URL ?param  ──►  vueData[param]         (inject trước khi data chạy)
+data[]      ──►  tạo state + action, auto-startup fetch
+controls    ──►  bind hai chiều vào state (v-model), gọi action (:action / v-on)
+watch       ──►  state đổi → chạy action → cập nhật state khác → UI re-render
+set         ──►  quyết định khung trang (title/menu/apiDomain) bao quanh controls
+```
+
+Typical loop: user acts on `controls` → state changes → `watch` fires → `API` action in `data` → `OUT` updates state → `controls` re-render.
+
+## Checklist
+
+1. `data[]`: state first → named actions → `{ "CALL": ... }` auto-startup last
+2. `watch`: every filter/dropdown has a watch → reload
+3. `controls`: start with grid wrapper; `w` on every item; dialogs in `hidden-container`; `v-on:click` not `@click`
+4. `set`: only when the page differs from project defaults
+5. Reference state as `vueData.` in controls/attr; valid JSON (no trailing commas)