@fui-org/fui-cli 1.2.0 → 1.3.1

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

@@ -0,0 +1,701 @@
+# Controls Patterns & Logic
+
+> 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`.)_
+
+---
+
+## Prefer `f-*` over `v-*`
+
+Use `v-*` only when no `f-*` equivalent exists (check [component-quickref.md](component-quickref.md)); `f-*` has built-in features and runtime integration.
+
+| 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                                                                                                           |
+
+Defaults auto-injected (`defaultControlAttr` in `scripts/component.js`) — declare a prop only to override:
+
+| 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`                                                                                                     |
+
+> **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)
+
+`getVueData(value, src)` resolves every string in `data[]` and `IN`:
+
+| 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": [
+  {
+    "a": "Hang So",              // has space → literal string "Hang So"
+    "b": 3,                      // number → 3
+    "c": true,                   // boolean → true
+    "d": null,                   // null → null
+    "e": "val1",                 // no space → JS eval: value of variable val1
+    "f": "val4.prop2",           // JS eval: vueData.val4.prop2
+    "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"
+    "l": "tuimuonghep{{val4.prop3}}chuoi" // {{ }} → "tuimuonghep10chuoi"
+  }
+]
+```
+
+`"val1"` = value of `val1`, not the string; literal needs ``"`val1"``.
+
+> ⚠️ **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.
+
+`{{ }}` takes any JS expression:
+
+```json
+"label": "Còn {{items.length}} bản ghi",
+"title": "Ngày {{moment().format('DD/MM/YYYY')}}",
+"flag": "Là array: {{Array.isArray(myList)}}"
+```
+
+---
+
+## 1. `data[]` keys and assignment
+
+### Key notation
+
+```json
+"data": [
+  {
+    "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, 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
+  }
+]
+```
+
+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).
+
+### Events/slots in `attr` — full form only
+
+Every event/slot of every component, incl. custom `f-*` and `$emit()` events:
+
+| 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
+// ❌ WRONG — shorthand, fails to load
+{ "el": "f-contest-list", "attr": { "@saved": "CALL(apiLoadContests)" } }
+
+// ✅ RIGHT
+{ "el": "f-contest-list", "attr": { "v-on:saved": "CALL(apiLoadContests)" } }
+```
+
+`#PARENT.field` / `#Win1.field` in `data[]` is FUI cross-window syntax, unrelated to Vue slot `#`.
+
+### Alias and JS init
+
+```json
+"GanLienGiaTri": "val1"   // GanLienGiaTri = current value of val1
+```
+
+Snapshot at `data[]` run, not reactive — use `watch` for reactivity.
+
+```json
+"data": [
+  {
+    "today":     "moment().format('YYYY-MM-DD')",
+    "ids":       "[1,2,3,4].map(x=>x*2)",
+    "firstItem": "dsUser[0]",
+    "total":     "dsItems.length"
+  }
+]
+```
+
+---
+
+## 2. Actions (`data`)
+
+Declare named action objects in `data`; invoke with `CALL`.
+
+### CORE RULE — one `{}` = ONE command; sequence = ARRAY `[]`
+
+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
+// ❌ WRONG — only CALL runs. EXE and MESS NEVER run.
+"CALLBACK": {
+    "EXE": "vueData.previewRows = []; vueData.excelRaw = [];",
+    "CALL": "getList",
+    "MESS": "Đã cập nhật dữ liệu tháng"
+}
+```
+
+```json
+// ✅ RIGHT — three commands, three objects, run in written order.
+"CALLBACK": [
+    { "EXE": "vueData.previewRows = []; vueData.excelRaw = [];" },
+    { "CALL": "getList" },
+    { "MESS": "Đã cập nhật dữ liệu tháng" }
+]
+```
+
+`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
+```
+
+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".
+
+Applies to `CALLBACK`, `ERRORCALLBACK`, `THEN`/`ELSE`, `CANCEL`, `:action`, `:update-api.new/edit/delete`, `watch`, `onclose`, named actions. When in doubt wrap: `[{…}]` is always valid.
+
+| 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`) |
+
+**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`).
+
+Assignment fragments (`{ "dlgOpen": false, "form.Name": "" }`) run only in the fallthrough branch; any command in the same object silently drops them:
+
+```json
+// ❌ WRONG — CALL runs, the three variables are NOT assigned
+{ "PageNum": 1, "Description": "", "IsPaper": false, "CALL": "reload" }
+
+// ✅ RIGHT
+[
+    { "PageNum": 1, "Description": "", "IsPaper": false },
+    { "CALL": "reload" }
+]
+```
+
+### Keys
+
+| 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": {
+  "API": "/api/users",
+  "IN": { "GroupID": "vueData.selectedGroup" },
+  "OUT": "userList",
+  "CALLBACK": { "MESS": "Loaded!" }
+}
+```
+
+```json
+"apiLoadData": {
+  "API": "/api/controller/action",
+  "IN": {
+    "Page": 1,
+    "Search": "vueData.searchText",
+    "ID": "item.ID"
+  },
+  "OUT": "items",
+  "CALLBACK": [
+    { "MESS": "Loaded!" },
+    { "CALL": "anotherAction" }
+  ]
+}
+```
+
+- 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.
+
+### URL interpolation
+
+`{{ }}` in `API` reads vueData:
+
+```json
+"getDetail": {
+  "API": "/ts/Student/{{StudentID}}",
+  "OUT": "studentDetail"
+},
+"getReport": {
+  "API": "/ts/Report/{{sYear}}/{{sMonth}}",
+  "OUT": "reportData"
+}
+```
+
+### ERROROUT / ERRORCALLBACK
+
+Default: full-screen error dialog. With `ERROROUT` nothing shows automatically — you handle it.
+
+```json
+"saveData": {
+  "API": "/ts/Student_Insert",
+  "IN": { "Name": "sName" },
+  "ERROROUT": {
+    "errStatus":  "status",
+    "errMessage": "responseJSON"
+  },
+  "ERRORCALLBACK": {
+    "MESS": "Lưu thất bại: {{errMessage.Message}}"
+  }
+}
+```
+
+`ERROROUT` maps the XHR error (`status` = HTTP code, `responseJSON` = parsed body); `ERRORCALLBACK` runs after.
+
+### METHOD / HEADER
+
+Defaults `METHOD = "POST"`, `HEADER = { authorization: token }`; override for GET or external APIs.
+
+```json
+"getPublicData": {
+  "API": "/ts/PublicData",
+  "METHOD": "GET",
+  "HEADER": { "x-api-key": "`my-api-key" },
+  "OUT": "publicData"
+}
+```
+
+### Literal strings in `IN`
+
+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'",
+    "title": "`Tiêu đề cố định"
+  }
+}
+```
+
+`attr` props without `:` are already plain strings (`"url": "/fp/module?mid=123"` needs no backtick).
+
+### CONFIRM + CANCEL
+
+`CONFIRM` (supports `{{ }}`) asks first; optional `CANCEL` runs on Cancel.
+
+```json
+"deleteItem": {
+  "CONFIRM": "Bạn có chắc muốn xóa {{dongChon.Name}}?",
+  "API": "/api/delete",
+  "IN": { "id": "dongChon.ID" },
+  "CALLBACK": { "CALL": "reloadData" },
+  "CANCEL": { "MESS": "Đã hủy thao tác" }
+}
+```
+
+### IF / THEN / ELSE
+
+```json
+"checkStatus": {
+  "IF": "status === 1",
+  "THEN": { "MESS": "Active" },
+  "ELSE": {
+    "IF": "status === 2",
+    "THEN": { "MESS": "Pending" },
+    "ELSE": { "MESS": "Inactive" }
+  }
+}
+```
+
+Condition is JS reading vueData directly (no `vueData.` prefix). THEN/ELSE may be a JS string: `"THEN": "vueData.x = 1"`.
+
+### MESS vs MESSBOX
+
+`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." }
+```
+
+### FUN: showMessage
+
+`title`; `message` (optional); `onclose` = action after closing (use instead of `MESS` when something must follow).
+
+```json
+{
+  "FUN": "showMessage",
+  "IN": {
+    "title": "`Xác nhận thành công",
+    "message": "`Dữ liệu đã được lưu. Tiếp tục?",
+    "onclose": {
+      "CALL": "reloadData"
+    }
+  }
+}
+```
+
+### CALL
+
+Actions stored in `data[]` are callable anywhere (CALLBACK, IF/THEN/ELSE, watch):
+
+```json
+"data": [
+  { "apiGetLogs": { "API": "/nema/Wifi_Log_today", "OUT": "dataTableLogs" } }
+]
+```
+
+```json
+{ "CALL": "apiGetLogs" }
+```
+
+### ARRAY + COL
+
+```json
+{
+  "danhSachID": {
+    "ARRAY": "dsHoaDon",
+    "COL": "DanhMucThuID"
+  }
+}
+// danhSachID = [32423, 4, 23, 4, 234, 2]
+```
+
+### OUT object — multiple SELECTs
+
+For SPs returning `data[0]`, `data[1]`...; prefer this over CALLBACK + EXE.
+
+```json
+"getReport": {
+  "API": "/ts/TS_Report",
+  "OUT": {
+    "tongSoLuong":    "data[0][0].Total",
+    "danhSachChiTiet": "data[1]",
+    "thongKe":         "data[2]"
+  }
+}
+```
+
+### MAP — `IN` + `OUT` only, no API
+
+```json
+{
+  "IN": {
+    "HoTen": "formData.FullName",
+    "MaSV": "formData.StudentID"
+  },
+  "OUT": "mappedData"
+}
+```
+
+```json
+{
+  "IN": { "HoTen": "formData.FullName" },
+  "OUT": { "displayName": "HoTen" }
+}
+```
+
+### EXE
+
+Only for logic action JSON can't express; `vueData` accessible; end with `;`.
+
+```json
+{ "EXE": "vueData.items = vueData.items.filter(x => x.active); " }
+```
+
+---
+
+## 3. Watchers (`watch`)
+
+Cascading/filter design: [watcher-patterns.md](watcher-patterns.md).
+
+```json
+"watch": {
+  "searchText": { "CALL": "apiLoadData" },
+  "selectedGroup": { "CALL": "apiLoadUsers" }
+}
+```
+
+`v_old` holds the previous value in watch actions/CALLBACK:
+
+```json
+"watch": {
+  "taoID": {
+    "backupID": "v_old.taoID",
+    "BAC": 12345
+  }
+}
+```
+
+Watch is shallow (reference only). `deep-watch` detects inner changes, runs before normal watches, costs more — use only when needed:
+
+```json
+"watch": {
+  "deep-watch": {
+    "formData": { "CALL": "autoSave" },
+    "selectedItems": { "CALL": "recalcTotal" }
+  },
+  "sModuleID": { "CALL": "reload" }
+}
+```
+
+---
+
+## 4. Table cell action context
+
+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
+{
+  "el": "t-button",
+  "text": "Tên",
+  "value": "ten",
+  "attr": {
+    ":label": "`${item.ten}-${vueData.val1}`",
+    ":action": [
+      { "$row": "item" },
+      {
+        "API": "/api/getDetail",
+        "OUT": "DETAIL",
+        "CALLBACK": {
+          "danhSach[index].kohienthi": true
+        }
+      },
+      { "MESS": "Row {{danhSach[index].ten}}" }
+    ]
+  }
+}
+```
+
+---
+
+## 5. URL parameters → vueData
+
+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
+→ vueData.p_router  = "/ts/newhocsinh"
+→ vueData.p_routers = ["ts", "newhocsinh"]
+→ vueData.id        = "12345"
+→ vueData.mod       = "abcdef"
+```
+
+```json
+"data": [
+  {
+    "IF": "typeof menu != 'undefined' && menu=='0'",
+    "THEN": { "v_Set.menu": false }
+  }
+]
+```
+
+---
+
+## 6. Layout (`controls`)
+
+> 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.
+
+**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`.
+
+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.
+
+### Vertical centering
+
+Verify each row's controls share a vertical center (esp. mixing input/select, button, icon, checkbox, label, differing heights).
+
+- 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" } }
+  ]
+}
+```
+
+### Exception — page is one custom 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
+[
+  {
+    "prop": "fluid pa-0",
+    "rows": [
+      {
+        "prop": "",
+        "cols": [
+          {
+            "el": "uc-main-ui",
+            "w": "12",
+            "attr": {}
+          }
+        ]
+      }
+    ]
+  }
+]
+```
+
+### Grid and control object
+
+```json
+{
+  "prop": "fluid grid-list-md",
+  "rows": [
+    {
+      "prop": "row wrap",
+      "cols": [
+        { "w": "6", "el": "v-text-field", "attr": { "label": "Tên", "v-model": "tenBien" } },
+        { "w": "6", "el": "v-btn", "innerHTML": "Submit" }
+      ]
+    }
+  ]
+}
+```
+
+```json
+{
+  "w": "6",
+  "el": "v-text-field",
+  "col": { "class": "py-0" },
+  "attr": { "label": "Tên", "v-model": "tenBien" },
+  "innerHTML": "..."
+}
+```
+
+| 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
+{
+  "el": "v-btn",
+  "w": 6,
+  "col": { "class": "text-center" },
+  "attr": {
+    ":disabled": "true",
+    "color": "primary",
+    "v-on:click": "CALL(vueData.submit)"
+  },
+  "innerHTML": "Submit"
+}
+```
+
+```json
+{ "el": "div", "w": "12", "innerHTML": "Xin chào {{formData.fullName}}" }
+```
+
+### Pixel `w` — REQUIRES `col: { "class": "shrink" }`
+
+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
+// ❌ WRONG — 300 has no effect, column still stretches full
+{ "el": "v-text-field", "w": 300, "attr": { "v-model": "tuKhoa" } }
+
+// ✅ RIGHT — shrink disables flex-grow, flex-basis 300px applies
+{ "el": "v-text-field", "w": 300, "col": { "class": "shrink" },
+  "attr": { "v-model": "tuKhoa" } }
+```
+
+Measured (chromium, 1200px, neighbour takes rest):
+
+| Declared                       | V2       | V3       |
+| ------------------------------ | -------- | -------- |
+| `w: 300`                       | 687px ❌ | 738px ❌ |
+| + `col: { "shrink": true }`    | 300px ✅ | 738px ❌ |
+| + `col: { "class": "shrink" }` | 300px ✅ | 300px ✅ |
+
+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.
+
+**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.
+
+### Toolbar row — every column `shrink` except `v-spacer`
+
+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": {} }
+  ]
+}
+```
+
+**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.
+
+Measured (1200px; 2 selects `w:150`/`w:180` + "Tìm" | `v-spacer` | 2 buttons; V3 / V2):
+
+|                                  | 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   |
+
+Row 2 is the common bug ("right-align these buttons" → spacer added, `shrink` forgotten).
+
+- `"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.
+
+### Responsive
+
+```json
+"attr": {
+  ":width": "$vuetify.breakpoint.mdAndUp ? '500px' : '100%'"
+}
+```
+
+---
+
+## 7. Common element patterns
+
+- 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.