@fui-org/fui-cli 2.1.4 → 2.2.0

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

@@ -1,303 +1,303 @@
-# FUI UI Patterns — Core
-
-> Owns: **core UI patterns: toolbar/filter, permission gate, UI design checklist**. Table/dialog/cross-window/layout live in separate `ui-*` files.
-
-Patterns taken from project **security-manager** — use as reference for new modules. Load specialised files as needed:
-
-| Need                                                                                   | File                                                     |
-| -------------------------------------------------------------------------------------- | -------------------------------------------------------- |
-| f-table + in-cell controls (t-check/t-button/t-select/t-menu, ctrl-update, chip-group) | [ui-table-cell-patterns.md](ui-table-cell-patterns.md)   |
-| Dialog/popup form (hidden-container, open dialog with row, checkbox-list)              | [ui-dialog-patterns.md](ui-dialog-patterns.md)           |
-| Sub-window & data exchange (`openWindow`, `#PARENT`/`#Win`)                            | [ui-crosswindow-patterns.md](ui-crosswindow-patterns.md) |
-| Layout (page-container, master-detail, v-switch, date init, dynamic label)             | [ui-layout-patterns.md](ui-layout-patterns.md)           |
-
----
-
-## 1. `data[]` structure
-
-`data` initialises state + actions, processed top to bottom.
-
-- Object with **no action key** (no API, CALL, IF…) → state init
-- Object whose **key is a function name** → named (reusable) action
-- Trailing `{ "API": ..., "OUT": ... }` or `{ "CALL": ... }` → runs automatically on load
-
-```json
-"data": [
-  {
-    "dsUser": [],
-    "dsGroup": [],
-    "sDepartment": null,
-    "dlUserInfo": false
-  },
-  {
-    "getDepartment": { "API": "SM_DepartmentSelectAll", "OUT": "dsDepartment" },
-    "getGroup":      { "API": "SM_Group_SelectAll",    "OUT": "dsGroup" },
-    "getUser": {
-      "API": "SM_Users_SelectByDepGroup",
-      "IN": { "GroupID": "sGroup", "DepartmentID": "sDepartment" },
-      "OUT": "dsUser"
-    }
-  },
-  { "CALL": "getDepartment" },
-  { "CALL": "getGroup" }
-]
-```
-
-> **Auto-startup**: trailing CALLs in `data[]` run on module load — no event handler needed.
-
----
-
-## 2. Cascading API init
-
-`CALLBACK` sets a value from the first API result; the next API runs via `watch`.
-
-```json
-"data": [
-  { "dsModule": [], "sModuleID": null },
-  {
-    "API": "/SM_Modules_SelectAll",
-    "OUT": "dsModule",
-    "CALLBACK": { "sModuleID": "dsModule[0].ModuleID" }
-  }
-],
-"watch": {
-  "sModuleID": { "CALL": "getFunctionRight" }
-}
-```
-
-> CALLBACK sets `sModuleID` → watch fires `getFunctionRight`. No manual call.
-
----
-
-## 3. Watch — cascading filter
-
-Filter change → reload. Several actions → array of CALL.
-
-```json
-"watch": {
-  "sDepartment": { "CALL": "getUser" },
-  "sGroup":      { "CALL": "getUser" },
-  "sModuleID": [
-    { "CALL": "getUserModule" },
-    { "CALL": "getSysRight" },
-    { "CALL": "getFunctionRight" }
-  ]
-}
-```
-
----
-
-## 4. Toolbar / filter row
-
-Row of filter fields + action buttons; `v-spacer` pushes the button group right.
-
-> **Rule: EVERY column is `"col": "shrink"` except `v-spacer`.** A non-`shrink` column takes a share of free space — including an empty-`w` column and buttons. Missing `shrink` → buttons stretch, gaps appear between buttons, and the trailing group doesn't reach the right edge even with `v-spacer`. Standard template + measurements: [controls-patterns.md](controls-patterns.md) §Toolbar row.
-
-```json
-{
-  "prop": "",
-  "cols": [
-    {
-      "el": "v-autocomplete",
-      "col": { "class": "shrink" },
-      "attr": {
-        "class": "flex-md-grow-0",
-        "style": "width:200px",
-        "v-model": "sGroup",
-        "label": "Group",
-        ":items": "dsGroup",
-        "item-text": "GroupName",
-        "item-value": "GroupID",
-        ":required": false
-      },
-      "w": "200"
-    },
-    {
-      "el": "v-text-field",
-      "col": { "class": "shrink" },
-      "attr": {
-        "class": "flex-md-grow-0",
-        "style": "width:200px",
-        "v-model": "UserID",
-        "label": "User ID",
-        "clearable": ""
-      },
-      "w": "200"
-    },
-    {
-      "el": "f-button",
-      "col": { "class": "shrink" },
-      "attr": {
-        ":checkvalid": false,
-        "color": "primary",
-        "label": "Tìm",
-        "icon-text": "mdi-magnify",
-        ":action": { "CALL": "getUser" }
-      }
-    },
-    { "el": "v-spacer", "attr": {} },
-    {
-      "el": "f-button",
-      "col": { "v-if": "vueData.user.SystemRight==9", "class": "shrink" },
-      "attr": {
-        ":checkvalid": false,
-        ":disabled": "!sGroup",
-        "color": "primary",
-        "label": "Add User",
-        "icon-text": "mdi-account-multiple-plus",
-        ":action": [{ "addNew": 1, "sUserID": "", "sUserName": "" }, { "dlUserInfo": true }]
-      }
-    }
-  ]
-}
-```
-
-- Filter fields: `w` in px (`>= 25`) + `col: "shrink"`. The `attr: { class: "flex-md-grow-0", style: "width:Xpx" }` pair above is **redundant** — `w` + `shrink` already gives that width (measured: `w:150` + `shrink` → exactly 150px on V2 and V3). It stays only because the example is copied from production; omit it in new code.
-- Search button right after the fields, also `col: "shrink"` (a non-shrink button stretches).
-- **Always `class: "shrink"` / `"col": "shrink"`, never `shrink: true`** — the bare attribute works only on V2; on V3 it's inert and the column goes full width.
-- `v-spacer` is the **only** non-`shrink` column — it must grow to push the following group right.
-- Admin Add/Delete buttons: after the spacer, permission `v-if` — `col: { "v-if": "…", "class": "shrink" }` (object form when extra keys are needed; keep `shrink`).
-- Right-align the whole row without `v-spacer`: `"prop": "row justify-end"`.
-
----
-
-## 5. Permission gating
-
-Show/hide by the user's `SystemRight`.
-
-```json
-"col": { "v-if": "vueData.user.SystemRight>1" }
-"col": { "v-if": "vueData.user.SystemRight==9" }
-```
-
-- `>1` — any user with rights (not the lowest level)
-- `==9` — top admin only
-
----
-
-## 6. IF/THEN/ELSE
-
-Branching inside an action or CALLBACK.
-
-```json
-{
-  "IF": "TypeLoad==1",
-  "THEN": { "CALL": "getComputer" },
-  "ELSE": {
-    "IF": "TypeLoad==2",
-    "THEN": { "CALL": "getComputerDinied" },
-    "ELSE": { "CALL": "getComputerNotVisited" }
-  }
-}
-```
-
-- Condition: JS expression using vueData fields directly (no `vueData.` prefix).
-- Nest IF/ELSE for multi-branch switch.
-
-Real use: module with several view modes (`TypeLoad`) — after an update, refresh the list currently shown.
-
-```json
-"data": [
-  { "TypeLoad": 1 }
-]
-```
-
----
-
-## 7. CALLBACK chaining
-
-Array CALLBACK → runs in order.
-
-> **Several commands MUST be an array, one `{}` per command.** Merging `CALL` + `MESS` + `EXE` into one object runs only **one** (priority `API` → `CALL` → `EXE` → `FUN` → `IF` → `MESS` → `MESSBOX`, each branch `return`s immediately); the rest are dropped silently — no error, no `[Vue warn]`. Full rule + runtime reason: [controls-patterns.md](controls-patterns.md) §CORE RULE.
-
-```json
-"CALLBACK": [
-  { "MESS": "Cập nhật thành công." },
-  { "dlUserInfo": false },
-  { "CALL": "getUser" }
-]
-```
-
-```json
-"CALLBACK": [
-  { "CALL": "getUserModule" },
-  { "sUserDeptSelected": [], "dlAddUser": false },
-  { "MESS": "Thêm user thành công." }
-]
-```
-
-Usual order: reload data → reset state → show message.
-
----
-
-## 8. `set` — module-level config
-
-`set` at module.json root configures the whole module.
-
-```json
-"set": {
-  "menu": false
-}
-```
-
-- `menu: false` — hide navigation menu (sub-windows, log viewers).
-
-> Module opened via `openWindow`: declare `"set": { "menu": false }` in the child module's module.json — **don't** pass `?menu=0` in the URL. Full pattern (incl. setting it dynamically from `data[]`): [ui-crosswindow-patterns.md](ui-crosswindow-patterns.md).
-
----
-
-## 9. CALLBACK with JS expression
-
-`{{ expression }}` in CALLBACK runs complex code after the API.
-
-```json
-"CALLBACK": "{{ _.forEach(dsUsers, (x)=> x.FunctionName = JSON.parse(x.FunctionName)) }}"
-```
-
-```json
-"CALLBACK": "{{ _.forEach(dsUserFunction, (x)=> x.FunctionName = JSON.parse(x.FunctionName)), _.forEach(dsUserFunction, (x)=> x.UserSysItem = JSON.parse(x.UserSysItem)) }}"
-```
-
-> Use when the API returns a JSON string that must be parsed to object/array before render.
-
----
-
-## 10. script.js — helpers
-
-`script.js` holds helpers called from `v-on:click` or actions. They access `vueData` directly; use for logic plain action JSON can't express.
-
-```javascript
-// script.js
-function setFunction(user, fc) {
-  vueData.sFunctionSelected = [];
-  vueData.sUserSelected = [];
-  vueData.sUserSelected.push(user);
-  if (!fc) return;
-  vueData.dsFunctionRight.map((item) => {
-    if (fc.some((fci) => fci.FunctionID == item.FunctionID)) {
-      vueData.sFunctionSelected.push(item.FunctionID.toString());
-    }
-  });
-}
-```
-
-Called from `v-on:click` in a header:
-
-```json
-"v-on:click": "vueData.dlFunction = true; CALL(setFunction(item, item.FunctionName));"
-```
-
----
-
-## UI design checklist
-
-> `module.json` structure checklist (`data[]` order, grid wrapper, `w`, `v-on:`, `set`, valid JSON) is in [module-json-anatomy.md](module-json-anatomy.md). Below is UI-specific only.
-
-1. **Toolbar row**: shrink filters + v-spacer + permission-gated buttons
-2. **f-table**: fixed-header, item-class for row highlight, correct item-key — [ui-table-cell-patterns.md](ui-table-cell-patterns.md)
-3. **Dialogs**: always in hidden-container, v-card[padding:0] + v-toolbar[dense flat] — [ui-dialog-patterns.md](ui-dialog-patterns.md)
-4. **menuChucNang**: define in data[], reference via t-menu in headers — [ui-table-cell-patterns.md](ui-table-cell-patterns.md)
-5. **ctrl-update**: simple CRUD; manual dialog for complex forms
-6. **CALLBACK**: chaining array — reload → reset state → MESS
-7. **#PARENT**: set at the top of data[] before startup CALLs — [ui-crosswindow-patterns.md](ui-crosswindow-patterns.md)
-8. **Permission**: `v-if: "vueData.user.SystemRight>1"` for admin-only sections
+# FUI UI Patterns — Core
+
+> Owns: **core UI patterns: toolbar/filter, permission gate, UI design checklist**. Table/dialog/cross-window/layout live in separate `ui-*` files.
+
+Patterns taken from project **security-manager** — use as reference for new modules. Load specialised files as needed:
+
+| Need                                                                                   | File                                                     |
+| -------------------------------------------------------------------------------------- | -------------------------------------------------------- |
+| f-table + in-cell controls (t-check/t-button/t-select/t-menu, ctrl-update, chip-group) | [ui-table-cell-patterns.md](ui-table-cell-patterns.md)   |
+| Dialog/popup form (hidden-container, open dialog with row, checkbox-list)              | [ui-dialog-patterns.md](ui-dialog-patterns.md)           |
+| Sub-window & data exchange (`openWindow`, `#PARENT`/`#Win`)                            | [ui-crosswindow-patterns.md](ui-crosswindow-patterns.md) |
+| Layout (page-container, master-detail, v-switch, date init, dynamic label)             | [ui-layout-patterns.md](ui-layout-patterns.md)           |
+
+---
+
+## 1. `data[]` structure
+
+`data` initialises state + actions, processed top to bottom.
+
+- Object with **no action key** (no API, CALL, IF…) → state init
+- Object whose **key is a function name** → named (reusable) action
+- Trailing `{ "API": ..., "OUT": ... }` or `{ "CALL": ... }` → runs automatically on load
+
+```json
+"data": [
+  {
+    "dsUser": [],
+    "dsGroup": [],
+    "sDepartment": null,
+    "dlUserInfo": false
+  },
+  {
+    "getDepartment": { "API": "SM_DepartmentSelectAll", "OUT": "dsDepartment" },
+    "getGroup":      { "API": "SM_Group_SelectAll",    "OUT": "dsGroup" },
+    "getUser": {
+      "API": "SM_Users_SelectByDepGroup",
+      "IN": { "GroupID": "sGroup", "DepartmentID": "sDepartment" },
+      "OUT": "dsUser"
+    }
+  },
+  { "CALL": "getDepartment" },
+  { "CALL": "getGroup" }
+]
+```
+
+> **Auto-startup**: trailing CALLs in `data[]` run on module load — no event handler needed.
+
+---
+
+## 2. Cascading API init
+
+`CALLBACK` sets a value from the first API result; the next API runs via `watch`.
+
+```json
+"data": [
+  { "dsModule": [], "sModuleID": null },
+  {
+    "API": "/SM_Modules_SelectAll",
+    "OUT": "dsModule",
+    "CALLBACK": { "sModuleID": "dsModule[0].ModuleID" }
+  }
+],
+"watch": {
+  "sModuleID": { "CALL": "getFunctionRight" }
+}
+```
+
+> CALLBACK sets `sModuleID` → watch fires `getFunctionRight`. No manual call.
+
+---
+
+## 3. Watch — cascading filter
+
+Filter change → reload. Several actions → array of CALL.
+
+```json
+"watch": {
+  "sDepartment": { "CALL": "getUser" },
+  "sGroup":      { "CALL": "getUser" },
+  "sModuleID": [
+    { "CALL": "getUserModule" },
+    { "CALL": "getSysRight" },
+    { "CALL": "getFunctionRight" }
+  ]
+}
+```
+
+---
+
+## 4. Toolbar / filter row
+
+Row of filter fields + action buttons; `v-spacer` pushes the button group right.
+
+> **Rule: EVERY column is `"col": "shrink"` except `v-spacer`.** A non-`shrink` column takes a share of free space — including an empty-`w` column and buttons. Missing `shrink` → buttons stretch, gaps appear between buttons, and the trailing group doesn't reach the right edge even with `v-spacer`. Standard template + measurements: [controls-patterns.md](controls-patterns.md) §Toolbar row.
+
+```json
+{
+  "prop": "",
+  "cols": [
+    {
+      "el": "v-autocomplete",
+      "col": { "class": "shrink" },
+      "attr": {
+        "class": "flex-md-grow-0",
+        "style": "width:200px",
+        "v-model": "sGroup",
+        "label": "Group",
+        ":items": "dsGroup",
+        "item-text": "GroupName",
+        "item-value": "GroupID",
+        ":required": false
+      },
+      "w": "200"
+    },
+    {
+      "el": "v-text-field",
+      "col": { "class": "shrink" },
+      "attr": {
+        "class": "flex-md-grow-0",
+        "style": "width:200px",
+        "v-model": "UserID",
+        "label": "User ID",
+        "clearable": ""
+      },
+      "w": "200"
+    },
+    {
+      "el": "f-button",
+      "col": { "class": "shrink" },
+      "attr": {
+        ":checkvalid": false,
+        "color": "primary",
+        "label": "Tìm",
+        "icon-text": "mdi-magnify",
+        ":action": { "CALL": "getUser" }
+      }
+    },
+    { "el": "v-spacer", "attr": {} },
+    {
+      "el": "f-button",
+      "col": { "v-if": "vueData.user.SystemRight==9", "class": "shrink" },
+      "attr": {
+        ":checkvalid": false,
+        ":disabled": "!sGroup",
+        "color": "primary",
+        "label": "Add User",
+        "icon-text": "mdi-account-multiple-plus",
+        ":action": [{ "addNew": 1, "sUserID": "", "sUserName": "" }, { "dlUserInfo": true }]
+      }
+    }
+  ]
+}
+```
+
+- Filter fields: `w` in px (`>= 25`) + `col: "shrink"`. The `attr: { class: "flex-md-grow-0", style: "width:Xpx" }` pair above is **redundant** — `w` + `shrink` already gives that width (measured: `w:150` + `shrink` → exactly 150px on V2 and V3). It stays only because the example is copied from production; omit it in new code.
+- Search button right after the fields, also `col: "shrink"` (a non-shrink button stretches).
+- **Always `class: "shrink"` / `"col": "shrink"`, never `shrink: true`** — the bare attribute works only on V2; on V3 it's inert and the column goes full width.
+- `v-spacer` is the **only** non-`shrink` column — it must grow to push the following group right.
+- Admin Add/Delete buttons: after the spacer, permission `v-if` — `col: { "v-if": "…", "class": "shrink" }` (object form when extra keys are needed; keep `shrink`).
+- Right-align the whole row without `v-spacer`: `"prop": "row justify-end"`.
+
+---
+
+## 5. Permission gating
+
+Show/hide by the user's `SystemRight`.
+
+```json
+"col": { "v-if": "vueData.user.SystemRight>1" }
+"col": { "v-if": "vueData.user.SystemRight==9" }
+```
+
+- `>1` — any user with rights (not the lowest level)
+- `==9` — top admin only
+
+---
+
+## 6. IF/THEN/ELSE
+
+Branching inside an action or CALLBACK.
+
+```json
+{
+  "IF": "TypeLoad==1",
+  "THEN": { "CALL": "getComputer" },
+  "ELSE": {
+    "IF": "TypeLoad==2",
+    "THEN": { "CALL": "getComputerDinied" },
+    "ELSE": { "CALL": "getComputerNotVisited" }
+  }
+}
+```
+
+- Condition: JS expression using vueData fields directly (no `vueData.` prefix).
+- Nest IF/ELSE for multi-branch switch.
+
+Real use: module with several view modes (`TypeLoad`) — after an update, refresh the list currently shown.
+
+```json
+"data": [
+  { "TypeLoad": 1 }
+]
+```
+
+---
+
+## 7. CALLBACK chaining
+
+Array CALLBACK → runs in order.
+
+> **Several commands MUST be an array, one `{}` per command.** Merging `CALL` + `MESS` + `EXE` into one object runs only **one** (priority `API` → `CALL` → `EXE` → `FUN` → `IF` → `MESS` → `MESSBOX`, each branch `return`s immediately); the rest are dropped silently — no error, no `[Vue warn]`. Full rule + runtime reason: [controls-patterns.md](controls-patterns.md) §CORE RULE.
+
+```json
+"CALLBACK": [
+  { "MESS": "Cập nhật thành công." },
+  { "dlUserInfo": false },
+  { "CALL": "getUser" }
+]
+```
+
+```json
+"CALLBACK": [
+  { "CALL": "getUserModule" },
+  { "sUserDeptSelected": [], "dlAddUser": false },
+  { "MESS": "Thêm user thành công." }
+]
+```
+
+Usual order: reload data → reset state → show message.
+
+---
+
+## 8. `set` — module-level config
+
+`set` at module.json root configures the whole module.
+
+```json
+"set": {
+  "menu": false
+}
+```
+
+- `menu: false` — hide navigation menu (sub-windows, log viewers).
+
+> Module opened via `openWindow`: declare `"set": { "menu": false }` in the child module's module.json — **don't** pass `?menu=0` in the URL. Full pattern (incl. setting it dynamically from `data[]`): [ui-crosswindow-patterns.md](ui-crosswindow-patterns.md).
+
+---
+
+## 9. CALLBACK with JS expression
+
+`{{ expression }}` in CALLBACK runs complex code after the API.
+
+```json
+"CALLBACK": "{{ _.forEach(dsUsers, (x)=> x.FunctionName = JSON.parse(x.FunctionName)) }}"
+```
+
+```json
+"CALLBACK": "{{ _.forEach(dsUserFunction, (x)=> x.FunctionName = JSON.parse(x.FunctionName)), _.forEach(dsUserFunction, (x)=> x.UserSysItem = JSON.parse(x.UserSysItem)) }}"
+```
+
+> Use when the API returns a JSON string that must be parsed to object/array before render.
+
+---
+
+## 10. script.js — helpers
+
+`script.js` holds helpers called from `v-on:click` or actions. They access `vueData` directly; use for logic plain action JSON can't express.
+
+```javascript
+// script.js
+function setFunction(user, fc) {
+  vueData.sFunctionSelected = [];
+  vueData.sUserSelected = [];
+  vueData.sUserSelected.push(user);
+  if (!fc) return;
+  vueData.dsFunctionRight.map((item) => {
+    if (fc.some((fci) => fci.FunctionID == item.FunctionID)) {
+      vueData.sFunctionSelected.push(item.FunctionID.toString());
+    }
+  });
+}
+```
+
+Called from `v-on:click` in a header:
+
+```json
+"v-on:click": "vueData.dlFunction = true; CALL(setFunction(item, item.FunctionName));"
+```
+
+---
+
+## UI design checklist
+
+> `module.json` structure checklist (`data[]` order, grid wrapper, `w`, `v-on:`, `set`, valid JSON) is in [module-json-anatomy.md](module-json-anatomy.md). Below is UI-specific only.
+
+1. **Toolbar row**: shrink filters + v-spacer + permission-gated buttons
+2. **f-table**: fixed-header, item-class for row highlight, correct item-key — [ui-table-cell-patterns.md](ui-table-cell-patterns.md)
+3. **Dialogs**: always in hidden-container, v-card[padding:0] + v-toolbar[dense flat] — [ui-dialog-patterns.md](ui-dialog-patterns.md)
+4. **menuChucNang**: define in data[], reference via t-menu in headers — [ui-table-cell-patterns.md](ui-table-cell-patterns.md)
+5. **ctrl-update**: simple CRUD; manual dialog for complex forms
+6. **CALLBACK**: chaining array — reload → reset state → MESS
+7. **#PARENT**: set at the top of data[] before startup CALLs — [ui-crosswindow-patterns.md](ui-crosswindow-patterns.md)
+8. **Permission**: `v-if: "vueData.user.SystemRight>1"` for admin-only sections