@fui-org/fui-cli 1.3.1 → 2.0.0

package/skills/fui-skill/references/controls-patterns.md

@@ -1,56 +1,48 @@
-# Controls Patterns & Logic
+# Controls Patterns & Logic
 
-> File này sở hữu: **value resolution (backtick / `{{ }}` / JS eval), action engine (API/IN/OUT/CALLBACK/CONFIRM/MESS/CALL/IF/EXE), key notation, grid wrapper `container > rows > cols`, control object, layout rules**. Bộ class/style được duyệt xem [controls-styling-vocabulary.md](controls-styling-vocabulary.md); tổng quan 4 thành phần module.json xem [module-json-anatomy.md](module-json-anatomy.md). *(Tier A — luôn nạp cùng `skill_get`.)*
-
-Guide to defining logic and layout in `module.json`.
+> Owns: value resolution (backtick / `{{ }}` / JS eval), action engine (API/IN/OUT/CALLBACK/CONFIRM/MESS/CALL/IF/EXE), key notation, grid wrapper `container > rows > cols`, control object, layout rules. Classes/styles: [controls-styling-vocabulary.md](controls-styling-vocabulary.md); module.json overview: [module-json-anatomy.md](module-json-anatomy.md). _(Tier A — loaded with `fui skill get`.)_
 
 ---
 
-## Ưu tiên FUI components — kiểm tra trước khi dùng `v-*`
-
-FUI đã xây dựng sẵn các `f-*` component với nhiều tính năng mặc định (sort, search, CRUD, inline action, form validation, ...) — dùng `f-*` sẽ ít code hơn và tận dụng được toàn bộ tích hợp runtime. Chỉ dùng `v-*` khi FUI chưa có equivalent phù hợp.
+## Prefer `f-*` over `v-*`
 
-| Ưu tiên dùng | Thay vì | Lý do ưu tiên |
-|---|---|---|
-| `f-table` | `v-data-table` (CRUD lẫn readonly) | sort/search/inline action/CRUD tích hợp sẵn; readonly = không khai `:update-api`; tự build headers khi bỏ `:headers`; hàng tổng qua `sum-format` |
-| `f-search` | `v-autocomplete` | API search, debounce, loading state có sẵn |
-| `f-button` | `v-btn` (khi cần action FUI) | hỗ trợ CALL, hotkey, form validation |
-| `f-date` / `f-time` | `v-text-field` + date parsing | picker + typed mask tích hợp sẵn |
-| `f-menu` | `v-menu + v-btn` dropdown | cấu hình đơn giản hơn, tích hợp icon/action/link |
-| `f-echart` | `<canvas>`, `v-chart`, lib khác | ECharts V5 — hỗ trợ mọi loại chart |
+Use `v-*` only when no `f-*` equivalent exists (check [component-quickref.md](component-quickref.md)); `f-*` has built-in features and runtime integration.
 
-> Trước khi dùng `v-*`, kiểm tra [component-quickref.md](component-quickref.md) — nếu có `f-*` equivalent thì ưu tiên dùng `f-*`.
+| Use                 | Instead of                         | Why                                                                                                                                   |
+| ------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `f-table`           | `v-data-table` (CRUD and readonly) | built-in sort/search/inline action/CRUD; readonly = omit `:update-api`; auto headers when `:headers` omitted; totals via `sum-format` |
+| `f-search`          | `v-autocomplete`                   | API search, debounce, loading                                                                                                         |
+| `f-button`          | `v-btn` (FUI action)               | CALL, hotkey, form validation                                                                                                         |
+| `f-date` / `f-time` | `v-text-field` + parsing           | picker + typed mask                                                                                                                   |
+| `f-menu`            | `v-menu + v-btn`                   | simpler, icon/action/link                                                                                                             |
+| `f-echart`          | `<canvas>`, `v-chart`, other libs  | ECharts V5, all chart types                                                                                                           |
 
-**Default attrs tự động** — FUI inject sẵn default props cho mỗi `f-*` component (xem `defaultControlAttr` trong `scripts/component.js`). Chỉ khai báo prop khi muốn **override** giá trị mặc định, không cần lặp lại default:
+Defaults auto-injected (`defaultControlAttr` in `scripts/component.js`) — declare a prop only to override:
 
-| Component | Default đã có sẵn (không cần khai báo lại) |
-|---|---|
-| `f-table` | `:dense true` · `:show-search true` · `:fixed-header true` · `:items-per-page 50` · `:hide-default-footer true` · `mobile-breakpoint 0` |
-| `f-button` | `color primary` · `elevation 0` |
-| `f-date` / `f-time` | `:dense true` · `:outlined true` · `:hide-details true` |
-| `f-search` | `:dense true` · `:outlined true` · `:hide-details true` · `:auto-select-first true` |
-| `f-menu` | `color primary` · `:depressed true` |
+| Component           | Defaults                                                                                                                                |
+| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `f-table`           | `:dense true` · `:show-search true` · `:fixed-header true` · `:items-per-page 50` · `:hide-default-footer true` · `mobile-breakpoint 0` |
+| `f-button`          | `color primary` · `elevation 0`                                                                                                         |
+| `f-date` / `f-time` | `:dense true` · `:outlined true` · `:hide-details true`                                                                                 |
+| `f-search`          | `:dense true` · `:outlined true` · `:hide-details true` · `:auto-select-first true`                                                     |
+| `f-menu`            | `color primary` · `:depressed true`                                                                                                     |
 
-> **Cảnh báo CRUD:** Không dùng `f-button` + `f-dialog` để mở form thêm mới — không hoạt động ổn định trong FUI V2. Dùng `ctrl-update` của `f-table` (`:update-form` + `:update-api`) cho mọi CRUD inline. Khi cần dialog riêng (form có logic đặc biệt, dynamic controls, multi-step...) → dựng `v-dialog` thủ công theo anatomy chuẩn phong cách f-dialog (`design_read("fui")` §4, `ui-dialog-patterns.md`).
+> **CRUD:** never `f-button` + `f-dialog` for an add form (unstable in V2). Use `f-table` `ctrl-update` (`:update-form` + `:update-api`). Special dialogs (custom logic, dynamic controls, multi-step) → hand-built `v-dialog` in f-dialog anatomy (`fui design read fui` §4, `ui-dialog-patterns.md`).
 
 ---
 
 ## 0. Value Resolution Rules (Fundamental)
 
-FUI dùng hàm `getVueData(value, src)` để giải thích mọi string value trong `data[]` và `IN` mapping. Hiểu đúng quy tắc này tránh lỗi set data sai.
-
-### Quy tắc xác định kiểu value
-
-| Dạng value | Cách xử lý | Kết quả |
-|---|---|---|
-| Primitive (number, boolean, object, array) | Lưu nguyên | Giá trị gốc |
-| String bắt đầu bằng `` ` `` | Lodash template (literal + `{{ }}` interpolation) | String sau khi render |
-| String có `{{ }}` | Lodash template với interpolation | String sau khi render |
-| String có spaces (không có backtick, không có `{{ }}`) | Lodash template → trả về literal | String đó |
-| String không có spaces, không backtick, không `{{ }}` | **Evaluated as JS expression** | Giá trị của expression |
-| `""` (empty string) | Empty string | `""` |
+`getVueData(value, src)` resolves every string in `data[]` and `IN`:
 
-### Ví dụ thực tế
+| Value                                      | Result                              |
+| ------------------------------------------ | ----------------------------------- |
+| Primitive (number, boolean, object, array) | as-is                               |
+| String starting with `` ` ``               | lodash template (literal + `{{ }}`) |
+| String containing `{{ }}`                  | lodash template                     |
+| String with spaces, no backtick/`{{ }}`    | literal                             |
+| String without spaces, backtick, `{{ }}`   | **evaluated as JS**                 |
+| `""`                                       | `""`                                |
 
 ```json
 "data": [
@@ -59,10 +51,10 @@ FUI dùng hàm `getVueData(value, src)` để giải thích mọi string value t
     "b": 3,                      // number → 3
     "c": true,                   // boolean → true
     "d": null,                   // null → null
-    "e": "val1",                 // no space → JS eval: giá trị của biến val1
+    "e": "val1",                 // no space → JS eval: value of variable val1
     "f": "val4.prop2",           // JS eval: vueData.val4.prop2
-    "g": "val5[1]",              // JS eval: phần tử thứ 2 của array val5
-    "h": "[val1]",               // JS eval: tạo array [giá_trị_val1]
+    "g": "val5[1]",              // JS eval: 2nd element of array val5
+    "h": "[val1]",               // JS eval: array [value_of_val1]
     "i": "[1,2,3].map(x=>x*2)", // no space → JS eval → [2,4,6]
     "j": "`Xin chào {{user.UserName}}",  // backtick → lodash template → "Xin chào Tuấn"
     "k": "tổng là {{a+b}} item", // {{ }} → lodash template → "tổng là 3 item"
@@ -71,13 +63,11 @@ FUI dùng hàm `getVueData(value, src)` để giải thích mọi string value t
 ]
 ```
 
-> **Quan trọng**: `"val1"` (no spaces) → FUI lấy GIÁ TRỊ của biến `val1`, KHÔNG phải string "val1". Muốn literal string "val1", phải dùng `` "`val1" ``.
+`"val1"` = value of `val1`, not the string; literal needs ``"`val1"``.
 
-> ⚠️ **Bảng trên KHÔNG áp cho `:attr`.** Chỉ `data[]` và `IN` mapping mới đi qua `getVueData()`. Giá trị của một binding (`:option`, `:config`, mọi `v-bind:`) đi **thẳng vào template compiler của Vue**, nên luật khác hẳn: chỉ nhận **một biểu thức thuần**, cấm `function(){}`/`var`/`return`/`;`. Vi phạm ⇒ trang trắng với 0 JS error, 0 `[Vue warn]`. Luật đầy đủ + cách chuyển logic sang `script.js` + `EXE`: [advanced-techniques.md](advanced-techniques.md) §1.
+> ⚠️ **Not for `:attr`.** Bindings (`:option`, `:config`, any `v-bind:`) go straight to Vue's compiler: one pure expression; no `function(){}`/`var`/`return`/`;`. Violation ⇒ blank page, 0 JS error, 0 `[Vue warn]`. Rules + moving logic to `script.js` + `EXE`: [advanced-techniques.md](advanced-techniques.md) §1.
 
-### String interpolation với `{{ }}`
-
-`{{ }}` dùng lodash template — có thể chứa bất kỳ JS expression nào:
+`{{ }}` takes any JS expression:
 
 ```json
 "label": "Còn {{items.length}} bản ghi",
@@ -87,61 +77,53 @@ FUI dùng hàm `getVueData(value, src)` để giải thích mọi string value t
 
 ---
 
-## 1. Khai báo và gán dữ liệu trong `data[]`
-
-### Key notation — Dot, Bracket, và Cross-window
+## 1. `data[]` keys and assignment
 
-Key trong `data[]` mapping không chỉ là tên biến đơn giản — FUI's `setValue` hỗ trợ đầy đủ path notation:
+### Key notation
 
 ```json
 "data": [
   {
-    "val":             "Hang So",   // biến đơn
+    "val":             "Hang So",   // simple variable
     "obj.prop":        "val1",      // dot notation → vueData.obj.prop
     "obj.nested.deep": true,        // multi-level dot
-    "arr[0].name":     "Tuan",      // bracket với literal index
-    "arr[val2].name":  "abc",       // bracket với biến index (val2 = 3 → arr[3])
-    "arr[0][val1].x":  "y",         // bracket với variable key (val1 = "Hang So")
-    "#PARENT.field":   "val1",      // ghi vào parent window
-    "#Win1.field":     "val1"       // ghi vào iframe Win1
+    "arr[0].name":     "Tuan",      // bracket, literal index
+    "arr[val2].name":  "abc",       // bracket, variable index (val2 = 3 → arr[3])
+    "arr[0][val1].x":  "y",         // bracket, variable key (val1 = "Hang So")
+    "#PARENT.field":   "val1",      // write to parent window
+    "#Win1.field":     "val1"       // write to iframe Win1
   }
 ]
 ```
 
-FUI **tự tạo object/array trung gian** nếu chưa tồn tại — dùng khi cập nhật một field sâu mà không phải gán lại cả object. Cùng luật này áp cho đích của `OUT` và mọi fragment gán dữ liệu.
+Missing intermediate objects/arrays are auto-created (also for `OUT` targets and assignment fragments) — no need to reassign the whole object. `#...` keys use `setWindowData` ([ui-patterns.md](ui-patterns.md) §Cross-window).
 
-> Khi key là `#...`, FUI gọi `setWindowData` thay vì `setValue` — xem [ui-patterns.md](ui-patterns.md) §Cross-window.
+### Events/slots in `attr` — full form only
 
-### Event và Slot trong `attr` — luôn viết đầy đủ, không viết tắt
+Every event/slot of every component, incl. custom `f-*` and `$emit()` events:
 
-Trong `module.json`, khi khai báo **event** hoặc **slot** cho bất kỳ component nào (kể cả `f-*` tùy biến như `f-contest-list`, không riêng `v-*`), luôn dùng dạng đầy đủ — không dùng ký hiệu viết tắt của Vue:
-
-| Loại | Viết tắt (Vue hỗ trợ trong `.vue`) | Dùng trong `module.json` |
-|---|---|---|
-| Event | `@click`, `@saved`, `@bất-kỳ-event-nào` | `v-on:click`, `v-on:saved`, `v-on:bất-kỳ-event-nào` |
-| Slot | `#default`, `#item.name` | `v-slot:default`, `v-slot:item.name` |
+| Kind  | Shorthand (`.vue` only)          | `module.json`                                |
+| ----- | -------------------------------- | -------------------------------------------- |
+| Event | `@click`, `@saved`, `@any-event` | `v-on:click`, `v-on:saved`, `v-on:any-event` |
+| Slot  | `#default`, `#item.name`         | `v-slot:default`, `v-slot:item.name`         |
 
 ```json
-// ❌ SAI — viết tắt, sẽ lỗi không load được
+// ❌ WRONG — shorthand, fails to load
 { "el": "f-contest-list", "attr": { "@saved": "CALL(apiLoadContests)" } }
 
-// ✅ ĐÚNG
+// ✅ RIGHT
 { "el": "f-contest-list", "attr": { "v-on:saved": "CALL(apiLoadContests)" } }
 ```
 
-Quy tắc này áp dụng cho **mọi event/slot của mọi component**, kể cả custom event do component tự `$emit()` (như `saved` ở trên) — không chỉ riêng DOM event chuẩn như `click`.
-
-> Không nhầm với `#PARENT.field` / `#Win1.field` — đó là cú pháp `#` riêng của FUI cho cross-window trong **`data[]`** (xem trên), khác hoàn toàn với slot shorthand `#` của Vue trong `attr`.
+`#PARENT.field` / `#Win1.field` in `data[]` is FUI cross-window syntax, unrelated to Vue slot `#`.
 
-### Gán giá trị liên kết (alias)
+### Alias and JS init
 
 ```json
-"GanLienGiaTri": "val1"   // GanLienGiaTri = giá trị hiện tại của val1
+"GanLienGiaTri": "val1"   // GanLienGiaTri = current value of val1
 ```
 
-Không reactive — chỉ snapshot tại thời điểm `data[]` chạy. Muốn reactive → dùng `watch`.
-
-### Data initialization với JS expressions
+Snapshot at `data[]` run, not reactive — use `watch` for reactivity.
 
 ```json
 "data": [
@@ -156,22 +138,16 @@ Không reactive — chỉ snapshot tại thời điểm `data[]` chạy. Muốn
 
 ---
 
-## 2. Component Actions (`data`)
-
-Actions are the "methods" of your module. They handle APIs, dialogs, and logic flow.
-Khai báo action thành object có tên trong `data`, gọi lại bằng `CALL`.
+## 2. Actions (`data`)
 
-### QUY TẮC NỀN — một object `{}` là MỘT lệnh; nhiều lệnh có thứ tự là MỘT MẢNG `[]`
+Declare named action objects in `data`; invoke with `CALL`.
 
-Đây là luật gốc của FUI, đọc trước mọi thứ khác trong mục này:
+### CORE RULE — one `{}` = ONE command; sequence = ARRAY `[]`
 
-> **Một lệnh / một tập lệnh = một object JSON `{}`** — vì bên trong một tập lệnh còn có thể có nhiều **tham số** và **tập lệnh con** lồng đệ quy (`IN`, `OUT`, `CALLBACK`, `THEN`/`ELSE`…).
-> **Nhiều lệnh chạy tuần tự = một MẢNG các object `[{…}, {…}, {…}]`** — mảng là cách DUY NHẤT diễn đạt "trước, rồi sau".
-
-Nhét nhiều lệnh vào chung một `{}` **không phải là "viết gọn"** — nó làm rơi lệnh:
+An object may hold parameters and nested sub-actions (`IN`, `OUT`, `CALLBACK`, `THEN`/`ELSE`…) but runs one command. An array is the ONLY way to sequence.
 
 ```json
-// ❌ SAI — chỉ CALL chạy. EXE và MESS KHÔNG BAO GIỜ chạy.
+// ❌ WRONG — only CALL runs. EXE and MESS NEVER run.
 "CALLBACK": {
     "EXE": "vueData.previewRows = []; vueData.excelRaw = [];",
     "CALL": "getList",
@@ -180,7 +156,7 @@ Nhét nhiều lệnh vào chung một `{}` **không phải là "viết gọn"**
 ```
 
 ```json
-// ✅ ĐÚNG — ba lệnh, ba object, chạy đúng thứ tự đã viết.
+// ✅ RIGHT — three commands, three objects, run in written order.
 "CALLBACK": [
     { "EXE": "vueData.previewRows = []; vueData.excelRaw = [];" },
     { "CALL": "getList" },
@@ -188,63 +164,52 @@ Nhét nhiều lệnh vào chung một `{}` **không phải là "viết gọn"**
 ]
 ```
 
-**Vì sao rơi** — `vueAction()` (`fastproject.js:407`, `fastproject-3.0.js:448`, giống hệt nhau ở V2 và V3) dò các key lệnh theo **thứ tự cố định**, và **mỗi nhánh `return` ngay**:
+`vueAction()` (`fastproject.js:407`, `fastproject-3.0.js:448`, same in V2/V3) checks keys in fixed order, each branch returns:
 
 ```
 IN (tham số, không return) → API ⏎ → CALL ⏎ → EXE ⏎ → FUN ⏎ → IF ⏎ → MESS ⏎ → MESSBOX ⏎ → (fallthrough) mapData
 ```
 
-Nên trong một object, **đúng một lệnh chạy** — lệnh có ưu tiên cao nhất, **không phải lệnh viết trước**. Ở ví dụ sai trên, `CALL` thắng `EXE` và `MESS` dù được viết ở giữa. Đảo thứ tự các dòng cũng không đổi được gì.
-
-Ngược lại, `runAction()` nhận mảng thì `_.forEach` từng phần tử qua `vueAction` ⇒ **mảng = tuần tự, giữ đúng thứ tự viết**.
-
-**Đây là lỗi hỏng-âm-thầm**: không JS error, không `[Vue warn]`, API vẫn chạy, chỉ là hai lệnh kia biến mất. Triệu chứng thường gặp: "sau khi lưu, danh sách có reload nhưng không thấy toast", hoặc "toast hiện mà form không reset".
-
-> Mọi chỗ nhận action đều theo luật này: `CALLBACK`, `ERRORCALLBACK`, `THEN`/`ELSE`, `CANCEL`, `:action`, `:update-api.new/edit/delete`, `watch`, `onclose`, và named action trong `data[]`. **Nghi ngờ thì bọc mảng** — mảng một phần tử `[{…}]` luôn hợp lệ.
-
-#### Key nào là LỆNH, key nào là THAM SỐ
-
-Chỉ nhóm "lệnh" mới bị luật một-object-một-lệnh. Tham số thì đi kèm lệnh trong **cùng** object là đúng.
+Highest priority wins, not first written; reordering changes nothing. `runAction()` runs arrays in order (`_.forEach`). Silent failure (no error, no `[Vue warn]`); symptoms: "list reloads but no toast", "toast shows but form not reset".
 
-| Nhóm | Key | Ghi chú |
-|---|---|---|
-| **Lệnh** (mỗi object chỉ chạy 1) | `API` · `CALL` · `EXE` · `FUN` · `IF` · `MESS` · `MESSBOX` | theo đúng thứ tự ưu tiên ở trên |
-| **Tham số** (đi chung, không tính là lệnh) | `IN` · `OUT` · `HEADER` · `METHOD` · `CALLBACK` · `ERROROUT` · `ERRORCALLBACK` · `THEN` · `ELSE` · `CONFIRM` · `CANCEL` | `CONFIRM`/`CANCEL` được `runAction` xử lý một tầng trên rồi mới gọi `vueAction` |
+Applies to `CALLBACK`, `ERRORCALLBACK`, `THEN`/`ELSE`, `CANCEL`, `:action`, `:update-api.new/edit/delete`, `watch`, `onclose`, named actions. When in doubt wrap: `[{…}]` is always valid.
 
-**Ngoại lệ duy nhất — `MESS` đi kèm `API`:** `callAPI` tự bắn toast khi thành công (`fastproject-3.0.js:755`, sau `OUT`, trước `CALLBACK`), nên ở đây `MESS` là **tham số của `API`**, không phải lệnh thứ hai. `{ "API": …, "IN": …, "MESS": …, "CALLBACK": … }` là đúng và rất thông dụng.
-Lưu ý: chỉ `MESS`, **không** áp cho `MESSBOX`; và chỉ với `API`, **không** với `FUN` (`runFunction` không đọc `MESS`).
+| Group                                         | Keys                                                                                                                                                                                   |
+| --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Commands** (one per object, priority above) | `API` · `CALL` · `EXE` · `FUN` · `IF` · `MESS` · `MESSBOX`                                                                                                                             |
+| **Parameters** (same object as command)       | `IN` · `OUT` · `HEADER` · `METHOD` · `CALLBACK` · `ERROROUT` · `ERRORCALLBACK` · `THEN` · `ELSE` · `CONFIRM` · `CANCEL` (`CONFIRM`/`CANCEL` handled by `runAction` before `vueAction`) |
 
-#### Đừng trộn key gán dữ liệu vào cùng object với lệnh
+**Sole exception:** `MESS` beside `API` is a parameter — `callAPI` toasts on success (`fastproject-3.0.js:755`, after `OUT`, before `CALLBACK`). `{ "API": …, "IN": …, "MESS": …, "CALLBACK": … }` is valid. Not `MESSBOX`; not with `FUN` (`runFunction` ignores `MESS`).
 
-Fragment gán dữ liệu (`{ "dlgOpen": false, "form.Name": "" }`) chạy ở **nhánh cuối cùng** của `vueAction` — nhánh này chỉ tới lượt khi **không** key lệnh nào khớp. Có lệnh trong cùng object thì mọi key gán bị bỏ im lặng:
+Assignment fragments (`{ "dlgOpen": false, "form.Name": "" }`) run only in the fallthrough branch; any command in the same object silently drops them:
 
 ```json
-// ❌ SAI — CALL chạy, ba biến kia KHÔNG được gán
+// ❌ WRONG — CALL runs, the three variables are NOT assigned
 { "PageNum": 1, "Description": "", "IsPaper": false, "CALL": "reload" }
 
-// ✅ ĐÚNG
+// ✅ RIGHT
 [
     { "PageNum": 1, "Description": "", "IsPaper": false },
     { "CALL": "reload" }
 ]
 ```
 
-### Bảng key của Action Protocol
+### Keys
 
-| Key | Mô tả |
-|---|---|
-| `API` | Endpoint cần gọi |
-| `IN` | Tham số đầu vào (tham chiếu `vueData.` hoặc `item.`) |
-| `OUT` | Lưu response vào biến (vd `"myList"`) — dạng object để tách nhiều SELECT |
-| `CALLBACK` | Action chạy sau khi thành công |
-| `ERROROUT` / `ERRORCALLBACK` | Bắt lỗi thủ công thay cho dialog lỗi mặc định |
-| `CONFIRM` / `CANCEL` | Hỏi xác nhận trước khi chạy / action khi user bấm Hủy |
-| `MESS` / `MESSBOX` | Toast / modal thông báo |
-| `CALL` | Gọi một named action khác |
-| `IF` / `THEN` / `ELSE` | Rẽ nhánh điều kiện |
-| `FUN` | Gọi hàm FUI có sẵn (`openWindow`, `showMessage`, ...) |
-| `ARRAY` + `COL` | Trích một cột từ mảng object thành mảng phẳng |
-| `EXE` | JS thô — dùng hạn chế |
+| Key                          | Meaning                                                      |
+| ---------------------------- | ------------------------------------------------------------ |
+| `API`                        | endpoint                                                     |
+| `IN`                         | input params (`vueData.` or `item.`)                         |
+| `OUT`                        | store response (e.g. `"myList"`); object form splits SELECTs |
+| `CALLBACK`                   | on success                                                   |
+| `ERROROUT` / `ERRORCALLBACK` | manual error handling                                        |
+| `CONFIRM` / `CANCEL`         | confirm first / on Cancel                                    |
+| `MESS` / `MESSBOX`           | toast / modal                                                |
+| `CALL`                       | run named action                                             |
+| `IF` / `THEN` / `ELSE`       | branch                                                       |
+| `FUN`                        | FUI function (`openWindow`, `showMessage`, ...)              |
+| `ARRAY` + `COL`              | column of object array → flat array                          |
+| `EXE`                        | raw JS, sparingly                                            |
 
 ```json
 "fetchUsers": {
@@ -255,9 +220,6 @@ Fragment gán dữ liệu (`{ "dlgOpen": false, "form.Name": "" }`) chạy ở *
 }
 ```
 
-Chi tiết từng key ở các mục bên dưới.
-
-### Standard API Call
 ```json
 "apiLoadData": {
   "API": "/api/controller/action",
@@ -274,13 +236,12 @@ Chi tiết từng key ở các mục bên dưới.
 }
 ```
 
-> Hai lệnh ⇒ **mảng hai object**. Gộp `MESS` và `CALL` vào một `{}` thì chỉ `CALL` chạy — xem §QUY TẮC NỀN ở trên.
-
-> **Không gán nested object trực tiếp trong action:** `{ "form": { "field": "item.field" } }` sẽ không hoạt động — dùng dot notation cho từng field: `{ "form.field": "item.field" }`. Nếu đang dùng `ctrl-update`, không cần quản lý form thủ công.
+- Two commands ⇒ array; merged, only `CALL` runs.
+- No nested object assignment: `{ "form": { "field": "item.field" } }` fails; use `{ "form.field": "item.field" }`. `ctrl-update` needs no manual form handling.
 
-### API URL Interpolation
+### URL interpolation
 
-`{{ }}` trong URL API được interpolate từ vueData:
+`{{ }}` in `API` reads vueData:
 
 ```json
 "getDetail": {
@@ -293,9 +254,9 @@ Chi tiết từng key ở các mục bên dưới.
 }
 ```
 
-### API Error Handling — ERROROUT / ERRORCALLBACK
+### ERROROUT / ERRORCALLBACK
 
-Mặc định, API lỗi sẽ hiện dialog lỗi toàn màn hình. Dùng `ERROROUT` + `ERRORCALLBACK` để bắt lỗi và xử lý thủ công:
+Default: full-screen error dialog. With `ERROROUT` nothing shows automatically — you handle it.
 
 ```json
 "saveData": {
@@ -311,11 +272,11 @@ Mặc định, API lỗi sẽ hiện dialog lỗi toàn màn hình. Dùng `ERROR
 }
 ```
 
-- `ERROROUT`: map từ XHR error object — các key thông dụng: `status` (HTTP status code), `responseJSON` (parsed error body)
-- `ERRORCALLBACK`: action chạy sau khi map ERROROUT (không hiện dialog mặc định)
-- Khi có `ERROROUT`, lỗi sẽ KHÔNG tự hiện — bạn phải xử lý hoàn toàn
+`ERROROUT` maps the XHR error (`status` = HTTP code, `responseJSON` = parsed body); `ERRORCALLBACK` runs after.
 
-### API Method và Header override
+### METHOD / HEADER
+
+Defaults `METHOD = "POST"`, `HEADER = { authorization: token }`; override for GET or external APIs.
 
 ```json
 "getPublicData": {
@@ -326,35 +287,26 @@ Mặc định, API lỗi sẽ hiện dialog lỗi toàn màn hình. Dùng `ERROR
 }
 ```
 
-- Mặc định: `METHOD = "POST"`, `HEADER = { authorization: token }`
-- Override khi cần GET hoặc custom header cho external API
-
-### Literal String Values (Important)
+### Literal strings in `IN`
 
-Apply this rule only for values passed inside action `IN` mapping.
-If a string has no spaces, FUI can treat it like an expression/variable in `IN`.  
-When you need a plain literal string, force it with:
-- Backtick prefix: ``"`myValue"`` (or closed ``"`myValue`"``)
-- Single quotes inside JSON string: `"'myValue'"`
+Only for `IN`: no-space strings may be evaluated. Force literal with backtick ``"`myValue"`` (or ``"`myValue`"``) or inner single quotes `"'myValue'"`. Always do this for `id`, `url`, and any key that must stay text.
 
 ```json
 {
   "FUN": "openWindow",
   "IN": {
-    "id":    "`winUser",
-    "url":   "'/fp/module?mid=123'",
+    "id": "`winUser",
+    "url": "'/fp/module?mid=123'",
     "title": "`Tiêu đề cố định"
   }
 }
 ```
 
-Đặc biệt cần ép literal cho các key như `id`, `url`, hoặc bất kỳ key nào trong `IN` phải giữ nguyên dạng text.
+`attr` props without `:` are already plain strings (`"url": "/fp/module?mid=123"` needs no backtick).
 
-For component props in `attr` without `:`, value is already a plain string prop and usually does not need wrapping — vd `"url": "/fp/module?mid=123"` trong `attr` đã là string literal, không cần backtick.
+### CONFIRM + CANCEL
 
-### Confirmation + CANCEL
-
-`CONFIRM` hiện dialog xác nhận trước khi thực thi. `CANCEL` (optional) chạy khi user bấm Hủy:
+`CONFIRM` (supports `{{ }}`) asks first; optional `CANCEL` runs on Cancel.
 
 ```json
 "deleteItem": {
@@ -366,9 +318,8 @@ For component props in `attr` without `:`, value is already a plain string prop
 }
 ```
 
-> `CONFIRM` string hỗ trợ `{{ }}` interpolation từ vueData.
+### IF / THEN / ELSE
 
-### Conditional Logic
 ```json
 "checkStatus": {
   "IF": "status === 1",
@@ -381,24 +332,20 @@ For component props in `attr` without `:`, value is already a plain string prop
 }
 ```
 
-> Condition: JS expression, truy cập vueData trực tiếp (không cần `vueData.` prefix).  
-> THEN/ELSE có thể là string JS: `"THEN": "vueData.x = 1"`.
+Condition is JS reading vueData directly (no `vueData.` prefix). THEN/ELSE may be a JS string: `"THEN": "vueData.x = 1"`.
 
 ### MESS vs MESSBOX
 
-| | MESS | MESSBOX |
-|---|---|---|
-| Hiển thị | Toast (góc trên, tự đóng) | Modal dialog (user phải đóng) |
-| Dùng khi | Thông báo thành công/thất bại | Cần user đọc và xác nhận đã thấy |
+`MESS` = auto-closing top toast (success/failure). `MESSBOX` = modal the user must close (must be read/acknowledged). Both support `{{ }}`.
 
 ```json
 { "MESS": "Lưu thành công!" }
 { "MESSBOX": "Phiên của bạn đã hết hạn. Vui lòng đăng nhập lại." }
 ```
 
-Cả hai hỗ trợ `{{ }}` interpolation.
+### FUN: showMessage
 
-### FUN: showMessage — Dialog thông báo có onclose
+`title`; `message` (optional); `onclose` = action after closing (use instead of `MESS` when something must follow).
 
 ```json
 {
@@ -413,13 +360,9 @@ Cả hai hỗ trợ `{{ }}` interpolation.
 }
 ```
 
-- `title`: tiêu đề dialog
-- `message`: nội dung chi tiết (optional)
-- `onclose`: action chạy sau khi user đóng dialog (thay thế `MESS` khi cần làm gì sau khi đọc xong)
-
-### CALL — Gọi action đã khai báo
+### CALL
 
-Action được lưu thành biến trong `data[]` → gọi lại bất cứ đâu bằng `CALL`:
+Actions stored in `data[]` are callable anywhere (CALLBACK, IF/THEN/ELSE, watch):
 
 ```json
 "data": [
@@ -431,29 +374,21 @@ Action được lưu thành biến trong `data[]` → gọi lại bất cứ đ
 { "CALL": "apiGetLogs" }
 ```
 
-`CALL` cũng dùng trong CALLBACK, IF/THEN/ELSE, hoặc watch để gọi action đã định nghĩa.
-
----
-
-### ARRAY — Trích xuất cột từ mảng cấu trúc
-
-Tạo mảng phẳng gồm tất cả giá trị của một cột từ array có cấu trúc:
+### ARRAY + COL
 
 ```json
 {
   "danhSachID": {
     "ARRAY": "dsHoaDon",
-    "COL":   "DanhMucThuID"
+    "COL": "DanhMucThuID"
   }
 }
 // danhSachID = [32423, 4, 23, 4, 234, 2]
 ```
 
----
-
-### OUT — Gán kết quả API vào nhiều biến
+### OUT object — multiple SELECTs
 
-Thay vì gán toàn bộ response vào một biến, dùng `OUT` dạng object để map từng phần:
+For SPs returning `data[0]`, `data[1]`...; prefer this over CALLBACK + EXE.
 
 ```json
 "getReport": {
@@ -466,19 +401,13 @@ Thay vì gán toàn bộ response vào một biến, dùng `OUT` dạng object
 }
 ```
 
-Dùng khi SP trả về nhiều SELECT (`data[0]`, `data[1]`...) — gán mỗi phần vào biến riêng thay vì dùng CALLBACK + EXE.
-
----
-
-### MAP — Mapping dữ liệu trong bộ nhớ (không qua API)
-
-Khi chỉ cần re-map dữ liệu giữa các biến mà không gọi API, dùng block chỉ có `IN` và `OUT`:
+### MAP — `IN` + `OUT` only, no API
 
 ```json
 {
   "IN": {
     "HoTen": "formData.FullName",
-    "MaSV":  "formData.StudentID"
+    "MaSV": "formData.StudentID"
   },
   "OUT": "mappedData"
 }
@@ -491,23 +420,19 @@ Khi chỉ cần re-map dữ liệu giữa các biến mà không gọi API, dùn
 }
 ```
 
----
+### EXE
 
-### EXE — Raw JavaScript
+Only for logic action JSON can't express; `vueData` accessible; end with `;`.
 
 ```json
 { "EXE": "vueData.items = vueData.items.filter(x => x.active); " }
 ```
 
-> Dùng khi cần logic phức tạp không thể diễn tả bằng action JSON. Có thể access `vueData` trực tiếp. Kết thúc bằng `;`.
-
 ---
 
 ## 3. Watchers (`watch`)
 
-Trigger actions automatically when data changes.
-
-For production-grade cascading and filter watcher design, see [watcher-patterns.md](watcher-patterns.md).
+Cascading/filter design: [watcher-patterns.md](watcher-patterns.md).
 
 ```json
 "watch": {
@@ -516,9 +441,7 @@ For production-grade cascading and filter watcher design, see [watcher-patterns.
 }
 ```
 
-### v_old — Giá trị trước khi thay đổi
-
-Trong CALLBACK hoặc action của watch, `v_old` chứa giá trị CŨ (trước khi thay đổi):
+`v_old` holds the previous value in watch actions/CALLBACK:
 
 ```json
 "watch": {
@@ -529,9 +452,7 @@ Trong CALLBACK hoặc action của watch, `v_old` chứa giá trị CŨ (trướ
 }
 ```
 
-### deep-watch — Watch nested object/array
-
-Mặc định watch là shallow (chỉ detect thay đổi reference). Dùng `deep-watch` để detect thay đổi bên trong:
+Watch is shallow (reference only). `deep-watch` detects inner changes, runs before normal watches, costs more — use only when needed:
 
 ```json
 "watch": {
@@ -543,19 +464,11 @@ Mặc định watch là shallow (chỉ detect thay đổi reference). Dùng `dee
 }
 ```
 
-> `deep-watch` được xử lý trước các watch thông thường. Tốn hiệu năng hơn — chỉ dùng khi cần thiết.
-
 ---
 
-## 4. Table Cell Action Context
+## 4. Table cell action context
 
-Khi action chạy từ cell trong `f-table` (t-button, t-check, t-select, t-menu, v-on:click), FUI inject thêm:
-
-| Variable | Giá trị |
-|---|---|
-| `item` | Object của row hiện tại |
-| `index` | Index của row trong array |
-| `$row` | Có thể set thủ công: `{ "$row": "item" }` |
+Actions from `f-table` cells (t-button, t-check, t-select, t-menu, v-on:click) get `item` (row), `index` (row index), and `$row` (settable: `{ "$row": "item" }`). Update one row via `danhSach[index].field` — the standard pattern:
 
 ```json
 {
@@ -579,13 +492,11 @@ Khi action chạy từ cell trong `f-table` (t-button, t-check, t-select, t-menu
 }
 ```
 
-> `danhSach[index].kohienthi` — update trực tiếp item trong array bằng `index` inject từ context. Đây là pattern chuẩn để update 1 item cụ thể trong table.
-
 ---
 
-## 5. URL Parameters → vueData
+## 5. URL parameters → vueData
 
-URL query params tự động được inject vào `vueData` khi module load:
+On load: `p_router` (path, no query), `p_routers` (segment array), each query param → same-named string variable.
 
 ```
 URL: https://fp.example.vn/ts/newhocsinh?id=12345&mod=abcdef
@@ -595,13 +506,6 @@ URL: https://fp.example.vn/ts/newhocsinh?id=12345&mod=abcdef
 → vueData.mod       = "abcdef"
 ```
 
-| Biến | Kiểu | Mô tả |
-|---|---|---|
-| `p_router` | string | Path sau domain, không có query string |
-| `p_routers` | array | Mảng các segment của path |
-| (query params) | string | Mỗi param trong query string → biến cùng tên |
-
-Dùng trong `data[]` để đọc URL params:
 ```json
 "data": [
   {
@@ -613,49 +517,36 @@ Dùng trong `data[]` để đọc URL params:
 
 ---
 
-## 6. Controls Layout (`controls`)
-
-> **Vuetify version (V2 framework):** FUI V2 dùng **Vuetify 1.5** — grid system dùng `v-container / v-layout / v-flex`. FUI V3 (fastproject-3.0.js) dùng **Vuetify 3** với grid `v-container / v-row / v-col`. Phần lớn module.json trong skill này viết theo cú pháp V2 (đại đa số project đang chạy); project mới dùng V3 thì tra bảng ngưỡng `w` V2/V3 bên dưới (mục `w dạng pixel`). Tham chiếu V2: https://v15.vuetifyjs.com/en/framework/grid/ — **đang tạo project mới và phải chọn V2 hay V3?** Mặc định là V3, xem [project-provisioning.md](project-provisioning.md) §Bước 1.
+## 6. Layout (`controls`)
 
-**MANDATORY**: All UI elements MUST be nested within a Grid System structure: **Container** > **Row** > **Col** > **Element**. Do NOT place elements directly at the root.
+> V2 = Vuetify 1.5 (`v-container / v-layout / v-flex`); V3 (fastproject-3.0.js) = Vuetify 3 (`v-container / v-row / v-col`). Examples use V2 syntax (most projects); for V3 see the `w` thresholds below. V2 ref: https://v15.vuetifyjs.com/en/framework/grid/. New project default is V3 — [project-provisioning.md](project-provisioning.md) §Step 1.
 
-### Default prop cho Container và Row
+**MANDATORY**: Container > Row > Col > Element. Nothing at root. No `children` key — nest via array `innerHTML`. `attr` = element attributes; `col` = grid-column attributes. Events `v-on:click`, never `@click`.
 
-| Phần | Default | Ghi chú |
-|---|---|---|
-| Container `prop` | `"fluid grid-list-md"` | Dùng mặc định này trước — chỉ thêm class khác khi có lý do cụ thể |
-| Row `prop` | `"row wrap"` hoặc `""` | Dùng mặc định này trước; hàng có nhiều loại control/chiều cao khác nhau dùng `"row wrap align-center"` |
+Defaults — use first, deviate only with reason: container `prop` `"fluid grid-list-md"`; row `prop` `"row wrap"` or `""`, mixed control types/heights `"row wrap align-center"`. Put spacing/alignment on `col` or `attr`, not container/row.
 
-> Spacing và alignment ưu tiên đặt trong `col` hoặc `el attr` hơn là trong container/row prop.
+### Vertical centering
 
-### Canh giữa control theo chiều dọc trong cùng một hàng
+Verify each row's controls share a vertical center (esp. mixing input/select, button, icon, checkbox, label, differing heights).
 
-Trước khi chốt một row, phải kiểm tra các control trong row có cùng trục giữa theo chiều dọc hay
-không — đặc biệt khi trộn input/select, button, icon, checkbox, label hoặc control có chiều cao khác
-nhau.
-
-- Mặc định cho hàng hỗn hợp: thêm `align-center` vào `prop` của row, ví dụ
-  `"prop": "row wrap align-center"`.
-- Nếu chỉ một control lệch trục và không nên thay alignment của cả hàng, đặt
-  `"col": { "class": "align-self-center" }` cho cột đó.
-- Không dùng `mt-*`, `mb-*` hoặc inline `style` để đẩy từng control lên/xuống nhằm giả lập canh giữa.
-- Sau khi dựng layout, tự rà lại row ở desktop và mobile; control xuống dòng phải vẫn có khoảng cách
-  tự nhiên, không bị lệch vì margin thủ công.
+- Mixed row: add `align-center` to row `prop`.
+- One stray control: `"col": { "class": "align-self-center" }` on it.
+- Never `mt-*`, `mb-*`, or inline `style` to fake centering.
+- Recheck desktop and mobile; wrapped controls keep natural spacing.
 
 ```json
 {
   "prop": "row wrap align-center",
   "cols": [
     { "el": "v-text-field", "w": 6, "attr": { "label": "Từ khóa", "v-model": "vueData.keyword" } },
-    { "el": "f-button", "w": "", "col": { "class": "shrink" },
-      "attr": { "label": "Tìm", "icon-text": "mdi-magnify" } }
+    { "el": "f-button", "w": "", "col": { "class": "shrink" }, "attr": { "label": "Tìm", "icon-text": "mdi-magnify" } }
   ]
 }
 ```
 
-### Ngoại lệ — Toàn bộ trang là một custom component (`fluid pa-0`)
+### Exception — page is one custom component
 
-Khi cả trang chỉ render **một component tự xây dựng duy nhất** (component tự lo toàn bộ layout/padding bên trong), đặt container `prop` thành `"fluid pa-0"` thay vì default `"fluid grid-list-md"` — tránh bị cộng thêm padding mặc định của grid bên ngoài component.
+If the page renders only one self-laid-out component (custom dashboard, `uc-*` app), container `prop` = `"fluid pa-0"` to avoid outer padding. Any other controls on the page (filter, header, sections) → keep `"fluid grid-list-md"`.
 
 ```json
 [
@@ -677,9 +568,8 @@ Khi cả trang chỉ render **một component tự xây dựng duy nhất** (com
 ]
 ```
 
-> Chỉ áp dụng khi component con là **toàn bộ nội dung trang** (dashboard tự thiết kế, custom app nhúng qua `uc-*`). Nếu trang còn control khác ngoài component (filter, header, nhiều section) → vẫn dùng default `"fluid grid-list-md"` để giữ spacing chuẩn giữa các phần.
+### Grid and control object
 
-### Basic Grid Structure
 ```json
 {
   "prop": "fluid grid-list-md",
@@ -695,25 +585,23 @@ Khi cả trang chỉ render **một component tự xây dựng duy nhất** (com
 }
 ```
 
-### Cấu trúc đầy đủ của một element trong `cols`
-
 ```json
 {
-  "w":        "6",
-  "el":       "v-text-field",
-  "col":      { "class": "py-0" },
-  "attr":     { "label": "Tên", "v-model": "tenBien" },
+  "w": "6",
+  "el": "v-text-field",
+  "col": { "class": "py-0" },
+  "attr": { "label": "Tên", "v-model": "tenBien" },
   "innerHTML": "..."
 }
 ```
 
-| Field | Truyền vào | Mô tả |
-|---|---|---|
-| `w` | `v-flex` | Shorthand width — `1`–`12` (grid) hoặc `>= 25` (pixel, **bắt buộc kèm `col: { "class": "shrink" }`** — xem mục dưới). **BẮT BUỘC với mọi item trong `cols`** |
-| `col` | `v-flex` | Các thuộc tính khác của v-flex: class, style, offset, align-self... |
-| `el` | tag component | Tag HTML (`div`, `span`), component Vuetify hoặc FUI (`v-text-field`, `f-button`, `uc-*`...) |
-| `attr` | element | Props/attrs/directive của chính component: `label`, `v-model`, `:disabled`, `v-on:click`. **KHÔNG dùng `@`** |
-| `innerHTML` | slot default | HTML string hoặc **mảng đệ quy** các Control Object lồng bên trong |
+| Field       | To           | Meaning                                                                                                       |
+| ----------- | ------------ | ------------------------------------------------------------------------------------------------------------- |
+| `w`         | `v-flex`     | **Required on every `cols` item.** `1`–`12` grid or `>= 25` px (px **requires `col: { "class": "shrink" }`**) |
+| `col`       | `v-flex`     | class, style, offset, align-self...                                                                           |
+| `el`        | tag          | `div`, `span`, Vuetify/FUI (`v-text-field`, `f-button`, `uc-*`...)                                            |
+| `attr`      | element      | props/attrs/directives (`label`, `v-model`, `:disabled`, `v-on:click`); **no `@`**                            |
+| `innerHTML` | default slot | HTML string (supports `{{ }}`) or recursive array of Control Objects                                          |
 
 ```json
 {
@@ -729,108 +617,74 @@ Khi cả trang chỉ render **một component tự xây dựng duy nhất** (com
 }
 ```
 
-### `w` dạng pixel — BẮT BUỘC kèm `col: { "class": "shrink" }`
-
-`w` có **hai chế độ**, runtime chọn theo ngưỡng chứ không theo ý định của người viết:
+```json
+{ "el": "div", "w": "12", "innerHTML": "Xin chào {{formData.fullName}}" }
+```
 
-- `w` nhỏ → **số cột grid**, sinh class `sm{w}` (V2) / `v-col-{w}` (V3)
-- `w` lớn → **bề rộng cố định px**, sinh inline `flex-basis: {w}px`
+### Pixel `w` — REQUIRES `col: { "class": "shrink" }`
 
-Nhưng cột grid mặc định là `flex-grow: 1` (`.flex` ở V2, `.v-col` ở V3), mà **`flex-grow` thắng `flex-basis`**: cột vẫn giãn ra chiếm hết chỗ trống, con số px **không có tác dụng nào**. Không lỗi JS, không `[Vue warn]` — chỉ là bề rộng khác điều mình khai.
+Small `w` → grid class `sm{w}` (V2) / `v-col-{w}` (V3). Large `w` → inline `flex-basis: {w}px`. But grid columns have `flex-grow: 1` (`.flex`/`.v-col`), which beats `flex-basis`: without `shrink` the px value silently does nothing.
 
 ```json
-// ❌ SAI — 300 hoàn toàn vô tác dụng, cột vẫn giãn full
+// ❌ WRONG — 300 has no effect, column still stretches full
 { "el": "v-text-field", "w": 300, "attr": { "v-model": "tuKhoa" } }
 
-// ✅ ĐÚNG — shrink tắt flex-grow, flex-basis 300px mới ăn
+// ✅ RIGHT — shrink disables flex-grow, flex-basis 300px applies
 { "el": "v-text-field", "w": 300, "col": { "class": "shrink" },
   "attr": { "v-model": "tuKhoa" } }
 ```
 
-Số đo thật (chromium, framework V2 + V3 thật, viewport 1200px, cột kế bên chiếm phần còn lại):
+Measured (chromium, 1200px, neighbour takes rest):
 
-| Khai | V2 | V3 |
-|---|---|---|
-| `w: 300` không có gì thêm | 687px ❌ | 738px ❌ |
-| `w: 300` + `col: { "shrink": true }` | 300px ✅ | 738px ❌ |
-| `w: 300` + `col: { "class": "shrink" }` | 300px ✅ | 300px ✅ |
+| Declared                       | V2       | V3       |
+| ------------------------------ | -------- | -------- |
+| `w: 300`                       | 687px ❌ | 738px ❌ |
+| + `col: { "shrink": true }`    | 300px ✅ | 738px ❌ |
+| + `col: { "class": "shrink" }` | 300px ✅ | 300px ✅ |
 
-**Chỉ `col: { "class": "shrink" }` đúng ở cả hai framework.** Dạng thuộc tính trần `col: { "shrink": true }` là prop của `v-flex` (FUI V2 = Vuetify 1.5, xem §Vuetify version ở trên); Vuetify 3 không có prop đó nên nó rơi xuống thành attribute DOM trơ. Class `shrink` thì ở V3 do chính `projectdefaultstyle.css` của FUI định nghĩa (`flex-grow:0; flex-shrink:1; flex-basis:content`), nên có ở cả hai. `col: { "class": "flex-grow-0" }` cũng cho 300px ở cả hai — dùng `shrink` cho thống nhất với phần còn lại của skill.
+Only `col: { "class": "shrink" }` works in both: `shrink: true` is a V2 `v-flex` prop, inert in Vuetify 3; the `shrink` class is defined for V3 in FUI's `projectdefaultstyle.css` (`flex-grow:0; flex-shrink:1; flex-basis:content`). `"flex-grow-0"` also works; use `shrink` for consistency.
 
-#### Ngưỡng khác nhau giữa V2 và V3 → tránh hẳn `w` 13–24
+**Never `w` 13–24.** V2 (`fastproject.js`) switches to px at `w > 12`; V3 (`fastproject-3.0.js`) at `w > 24`, so V3 `w: 20` emits `v-col-20`, which doesn't exist (only `.v-col-1`…`.v-col-12`) → no width, equal split (measured `flex-basis: 0px`, 600px). Rule: `w` is `1`–`12` or `>= 25` + shrink. `fui module validate` warns on both (including `cols` nested in `innerHTML`) — run it before publishing.
 
-| | Ngưỡng chuyển sang px | `w` = 20 cho ra |
-|---|---|---|
-| V2 (`fastproject.js`) | `w > 12` | `flex-basis: 20px` — px, hoạt động |
-| V3 (`fastproject-3.0.js`) | `w > 24` | class `v-col-20` — **Vuetify 3 chỉ định nghĩa `.v-col-1` … `.v-col-12`** |
+### Toolbar row — every column `shrink` except `v-spacer`
 
-Ở V3, `w` từ 13 đến 24 sinh ra một class **không tồn tại**: cột không có bề rộng nào cả, rơi về chia đều (đo được: `w: 20` → `flex-basis: 0px`, rộng 600px). Đây là vùng chết — cùng một `w` cho hai kết quả trái ngược trên hai framework.
-
-> **Luật:** `w` chỉ dùng `1`–`12` (chia cột) hoặc **`>= 25`** (pixel, kèm `col: { "class": "shrink" }`). Không bao giờ dùng 13–24.
-
-`module_validate` kiểm cả hai vế này (warning, quét cả `cols` lồng trong `innerHTML`) — chạy trước khi publish thì không phải phát hiện qua ảnh render.
-
-### Hàng nhiều control (toolbar) — CHUẨN MỰC: mọi cột `shrink`, trừ `v-spacer`
-
-Đây là hàng phổ biến nhất trong FUI: vài filter + nút thao tác bên trái, một nhóm nút đẩy sang phải. **Khuôn chuẩn — chép nguyên rồi thay control:**
+Canonical template (filters + buttons left, group pushed right):
 
 ```json
 {
   "prop": "row",
   "cols": [
-    { "el": "v-select",         "w": "150", "col": "shrink", "attr": {} },
-    { "el": "v-select",         "w": "180", "col": "shrink", "attr": {} },
-    { "el": "f-button",         "w": "",    "col": "shrink", "attr": {} },
-    { "el": "v-spacer",         "w": ""                                 },
-    { "el": "f-excel-reader",               "col": "shrink", "attr": {} },
-    { "el": "f-button",         "w": "",    "col": "shrink", "attr": {} }
+    { "el": "v-select", "w": "150", "col": "shrink", "attr": {} },
+    { "el": "v-select", "w": "180", "col": "shrink", "attr": {} },
+    { "el": "f-button", "w": "", "col": "shrink", "attr": {} },
+    { "el": "v-spacer", "w": "" },
+    { "el": "f-excel-reader", "col": "shrink", "attr": {} },
+    { "el": "f-button", "w": "", "col": "shrink", "attr": {} }
   ]
 }
 ```
 
-> **Luật:** trong một hàng chứa nhiều control điều khiển, **MỌI cột đều `"col": "shrink"`** — kể cả cột `w` rỗng. Ngoại lệ **duy nhất** là `v-spacer`: nó phải giãn được thì mới đẩy được nhóm sau sang phải, cho nó `shrink` là vô hiệu hoá chính nó.
-
-**`w` rỗng KHÔNG có nghĩa là "tự co theo nội dung".** `fastproject*.js` bọc toàn bộ phần xử lý bề rộng trong `if (c.w)`, nên `w: ""` sinh ra **không class, cũng không `flex-basis`** — cột còn trơ là `.v-col` / `.flex` với `flex-grow: 1`, tức **chia đều phần trống** y như mọi cột khác. Nút bị kéo dãn ra, các nút cách nhau những khoảng trống bằng nhau, và nhóm cuối hàng không sát mép phải.
-
-Số đo thật (chromium, framework V2 + V3 thật, viewport 1200px; hàng gồm 2 select `w:150`/`w:180` + nút "Tìm" | `v-spacer` | 2 nút cuối):
-
-| | select `w:150` | nút "Tìm" | `v-spacer` | Kết quả nhìn thấy |
-|---|---|---|---|---|
-| Không cột nào `shrink` | 271 / 240 ❌ | 145 / 154 | 145 / 90 | filter phình, mọi thứ dàn đều |
-| **Chỉ `v-spacer`, các cột khác không `shrink`** | 150 / 150 | **218 / 198** ❌ | 218 / 134 | **nút phình, hở khoảng giữa các nút, nhóm cuối không sát phải** |
-| `shrink` cả `v-spacer` | 150 / 150 | 88 / 64 | **24 / 0** ❌ | cả hàng dồn về trái, mất hẳn canh phải (Σ 780/662 trên 1200px) |
-| **`shrink` mọi cột trừ `v-spacer`** | 150 / 150 ✅ | 88 / 64 ✅ | **445 / 537** ✅ | filter đúng px, nút vừa chữ, nhóm cuối sát mép phải |
-
-*(số bên trái = V3, bên phải = V2)*
+**Rule:** every control column gets `"col": "shrink"`, including empty-`w` ones. Sole exception: `v-spacer` (shrinking it disables it). Empty `w` ≠ fit content: width logic is inside `if (c.w)`, so `w: ""` emits nothing and the column (`flex-grow: 1`) takes an equal share of free space. Any non-`shrink` column gets a share; in a toolbar only `v-spacer` should.
 
-Hàng thứ hai chính là lỗi hay gặp nhất: nghe **"cho hai nút này canh phải"** thì chỉ chèn `v-spacer` mà quên `shrink`. `v-spacer` lúc đó cũng chỉ là một cột `flex-grow: 1` ngang hàng với các nút — nó không "đẩy" được gì cả, chỉ nhận đúng một phần bằng nhau. Muốn hai nút **sát nhau và sát mép phải** thì hai nút đó **bắt buộc** phải hết giãn, nghĩa là phải có `shrink`.
+Measured (1200px; 2 selects `w:150`/`w:180` + "Tìm" | `v-spacer` | 2 buttons; V3 / V2):
 
-Ghi nhớ theo hệ quả chứ không theo quy tắc rời: **cột nào không `shrink` là cột được chia phần trống.** Trong một hàng toolbar, thứ duy nhất đáng được chia phần trống là khoảng trắng — tức `v-spacer`.
+|                                  | select `w:150` | "Tìm"            | `v-spacer`       | Result                                         |
+| -------------------------------- | -------------- | ---------------- | ---------------- | ---------------------------------------------- |
+| no `shrink`                      | 271 / 240 ❌   | 145 / 154        | 145 / 90         | filters bloat, evenly spread                   |
+| **`v-spacer` only, no `shrink`** | 150 / 150      | **218 / 198** ❌ | 218 / 134        | buttons bloat, gaps, end group not flush right |
+| `shrink` incl. `v-spacer`        | 150 / 150      | 88 / 64          | **24 / 0** ❌    | row packs left (Σ 780/662 of 1200px)           |
+| **`shrink` all but `v-spacer`**  | 150 / 150 ✅   | 88 / 64 ✅       | **445 / 537** ✅ | exact px, buttons fit, end group flush right   |
 
-Vài chi tiết đi kèm:
-
-- `col` viết được **chuỗi ngắn** (`"col": "shrink"`) hoặc **object** (`"col": { "class": "shrink" }`) — tương đương nhau; chuỗi ngắn gọn hơn cho toolbar. Cần thêm thứ khác (`v-if`, `style`…) thì dùng object và giữ `class: "shrink"` bên trong.
-- **Không bao giờ là `"col": { "shrink": true }`** — dạng thuộc tính trần chỉ ăn ở V2 (xem mục trên).
-- Cột **không** có `v-spacer` mà muốn canh phải cả hàng: đặt `prop` của row là `"row justify-end"` thay vì chèn spacer.
-- Cần nhiều hơn một nhóm (trái | giữa | phải): chèn **hai** `v-spacer`, mỗi cái vẫn không `shrink`.
-- Hàng **form nhập liệu** thì ngược lại — ở đó các field *nên* chia cột (`w` 1–12, không `shrink`) để co giãn theo màn hình. `shrink` là chuẩn cho **hàng điều khiển**, không phải cho mọi hàng.
-
-### `innerHTML` Supports `{{ }}`
-
-`innerHTML` dạng string hỗ trợ Vue template interpolation để bind text reactive:
-
-```json
-{ "el": "div", "w": "12", "innerHTML": "Xin chào {{formData.fullName}}" }
-```
+Row 2 is the common bug ("right-align these buttons" → spacer added, `shrink` forgotten).
 
-### Layout Rules — 4 quy tắc cứng
+- `"col": "shrink"` ≡ `"col": { "class": "shrink" }`; use the object when adding `v-if`, `style`…, keeping `class: "shrink"`.
+- Never `"col": { "shrink": true }` (V2 only).
+- Right-align a whole row without spacer: row `prop` `"row justify-end"`.
+- Left | center | right: two `v-spacer`s, neither `shrink`.
+- Data-entry form rows are the opposite: fields use `w` 1–12, no `shrink`. `shrink` is for control rows only.
 
-- **Wrapper**: LUÔN bắt đầu bằng Grid Wrapper (`container > rows > cols`), không đặt element ở gốc.
-- **Không có key `children`**: lồng control bằng `innerHTML` dạng mảng.
-- **Attributes**: `attr` cho thuộc tính của element; `col` cho thuộc tính của cột grid.
-- **Events**: dùng `v-on:click` (JSON hợp lệ), không dùng `@click`.
+### Responsive
 
-### Responsive Forms
 ```json
 "attr": {
   ":width": "$vuetify.breakpoint.mdAndUp ? '500px' : '100%'"
@@ -839,9 +693,9 @@ Vài chi tiết đi kèm:
 
 ---
 
-## 7. Common Element Patterns
+## 7. Common element patterns
 
-- **HTML Content**: Use `innerHTML` for text or simple HTML.
-- **Events**: `v-on:click`, `v-on:change`. wrap logic in `CALL()`.
-- **Visibility**: Use `v-if` (pre-render) or `v-show` (CSS toggle).
-- **Loops**: `v-for` is rarely used directly in `module.json`. Use `f-table` for lists or recursive partials.
+- Text/simple HTML: `innerHTML`.
+- Events: `v-on:click`, `v-on:change`; wrap logic in `CALL()`.
+- Visibility: `v-if` (pre-render) or `v-show` (CSS toggle).
+- Lists: avoid raw `v-for`; use `f-table` or recursive partials.