@fui-org/fui-cli 1.2.1 → 1.3.2

package/skills/fui-skill-cli/references/ui-layout-patterns.md

@@ -0,0 +1,176 @@
+# FUI Layout Patterns — page-container, master-detail, switch, dynamic label
+
+> Owns: **page layout patterns: sticky page-container, 2-column master-detail, v-switch, date init, dynamic label**.
+
+Layout and helper-control patterns, drawn from project **security-manager**. See also: [ui-patterns.md](ui-patterns.md), [ui-table-cell-patterns.md](ui-table-cell-patterns.md), [module-structure.md](module-structure.md).
+
+---
+
+## 1. Date init with moment()
+
+```json
+"data": [
+  {
+    "TuNgay":  "moment().format('YYYY-MM-DD')",
+    "DenNgay": "moment().format('YYYY-MM-DD')"
+  }
+]
+```
+
+> The value is a JS expression string, eval'd at init. `moment()` is available in the FUI runtime.
+
+---
+
+## 2. page-container + page-navigation
+
+Use for a fixed filter bar on top with scrolling content below.
+
+```json
+{
+  "prop": "page-container grid-list-md fluid",
+  "rows": [
+    {
+      "prop": "page-navigation",
+      "cols": [
+        { "el": "f-date", "attr": { "v-model": "TuNgay", "label": "Từ ngày", "date-add": 0 }, "w": "2" },
+        { "el": "f-date", "attr": { "v-model": "DenNgay", "label": "Tới ngày", "date-add": 0 }, "w": "2" },
+        {
+          "el": "f-button",
+          "attr": {
+            "color": "primary",
+            "icon-text": "mdi-filter",
+            "label": "Tìm",
+            ":action": { "CALL": "getLogData" }
+          },
+          "w": 3
+        }
+      ]
+    },
+    {
+      "prop": "",
+      "cols": [{ "el": "f-table", "attr": { "label": "Log viewer", ":items": "LogData" } }]
+    }
+  ]
+}
+```
+
+- `page-container` + `page-navigation` → sticky top filter bar
+- `f-table` without `:update-api` → readonly; without `:headers` → headers auto-built from data
+
+---
+
+## 3. Dynamic label from state
+
+Use `:label` with an expression to show context.
+
+```json
+{
+  "el": "f-title",
+  "attr": {
+    ":label": "sFullName + ` - ` + sDepartment"
+  }
+}
+```
+
+```json
+{
+  "el": "f-table",
+  "attr": {
+    ":label": "`${fTableTitle==''? 'Computer list' : fTableTitle}`"
+  }
+}
+```
+
+---
+
+## 4. v-switch — toggle with label
+
+```json
+{
+  "el": "v-layout",
+  "attr": {},
+  "innerHTML": [
+    {
+      "el": "v-switch",
+      "attr": {
+        "v-model": "switchResetPassword",
+        ":required": false,
+        "label": "Đặt lại mật khẩu"
+      },
+      "w": "12"
+    }
+  ]
+}
+```
+
+Combine with `v-if` to show/hide extra fields:
+
+```json
+{
+  "el": "v-layout",
+  "attr": { "v-if": "switchResetPassword" },
+  "innerHTML": [...]
+}
+```
+
+---
+
+## 5. Two-column master-detail
+
+Left table row pick → watch → load right table. No new window needed.
+
+> Detail button in a table cell: choose `t-button` vs `t-menu` per [ui-table-cell-patterns.md](ui-table-cell-patterns.md) — for master-detail the action is "view/load related data", so use `t-button`.
+
+**`data[]` and watch:**
+
+```json
+"data": [
+  { "dsParent": [], "dsDetail": [], "selectedId": null },
+  {
+    "getParent": { "API": "/SM_Parent_Select", "OUT": "dsParent" },
+    "getDetail": {
+      "API": "/SM_Detail_Select",
+      "IN": { "ParentID": "selectedId" },
+      "OUT": "dsDetail"
+    }
+  },
+  { "CALL": "getParent" }
+],
+"watch": {
+  "selectedId": { "CALL": "getDetail" }
+}
+```
+
+**`t-button` column in the left table:**
+
+```json
+{
+  "text": "Chi tiết",
+  "value": "ParentID",
+  "align": "center",
+  "el": "t-button",
+  "attr": {
+    "icon-text": "mdi-eye",
+    "color": "primary",
+    ":outlined": true,
+    ":action": { "selectedId": "item.ParentID" }
+  }
+}
+```
+
+**2-column layout:**
+
+```json
+{
+  "prop": "fluid grid-list-md",
+  "rows": [
+    {
+      "prop": "row wrap",
+      "cols": [
+        { "w": 5, "el": "f-table", "attr": { ":items": "dsParent", "item-key": "ParentID", ":headers": [...] } },
+        { "w": 7, "el": "f-table", "attr": { ":items": "dsDetail", "item-key": "DetailID", ":headers": [...] } }
+      ]
+    }
+  ]
+}
+```

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

@@ -0,0 +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

package/skills/fui-skill-cli/references/ui-screenshot-review.md

@@ -0,0 +1,95 @@
+# UI review from screenshots
+
+> Owns: **reading and assessing UI screenshots (user-sent or from `--render`)**.
+
+Sources: (1) **user screenshot in chat** ("why is it ugly", "make it nicer", or an image + bug description); (2) **`fui module simulate --render`** — `render.png` (inline), `render-full.png`, `render-dialog.jpg`.
+
+Act as design QA: scan with the checklist; map every finding to a **concrete code cause** (controls[i] in module.json, class/style, CSS in header.html) + fix. No vague "doesn't look good".
+
+**MANDATORY — FIX findings, don't just report them.** Stuck/overlapping text (too little gap), misaligned controls, abnormal whitespace between controls are bugs **to fix in the same turn**, like hard rendering bugs. "Noted in the report" ≠ done. Ask the user only when design intent is unclear (e.g. should two blocks be on separate rows); otherwise fix and re-render (step 4).
+
+---
+
+## Workflow
+
+1. **Establish context** first:
+   - App-mode (CRUD/admin — aesthetic standard `fui design read fui`) or Web-mode (landing — chosen brand DESIGN.md)?
+   - Desktop or mobile? (narrow/portrait image → judge by responsive standards)
+   - module.json in workspace? Yes → cross-check image ↔ controls to pinpoint the fix; no → comment on the image, ask for module.json if a fix is needed
+2. **Scan with checklist A→D**, record each finding.
+3. **Report as a table**: `Finding | Severity (bug/should fix/suggestion) | Location in image | Likely cause | Proposed fix`.
+4. **Fix → re-render → compare** (required for every A/B finding): with workspace + Playwright, edit module.json, run `fui module simulate --render` (same viewport/device as the original if guessable), compare with the user's image; repeat until clean. `--render` auto-detects stuck/overlapping text (bounding rects, see A) and prints it in DOM AUDIT with "PHẢI sửa, không được bỏ qua" — fix it this turn; don't hand it to the user.
+
+Blurry/cropped/insufficient image → ask the user to recapture the specific area; don't guess.
+
+---
+
+## Scan checklist
+
+### A. Hard rendering bugs (must fix)
+
+- Abnormal empty area: component didn't render (empty app, blank card, white/0-size chart)
+- Leaked error text: `undefined`, `NaN`, `[object Object]`, exception messages, keys instead of values
+- Horizontal overflow: horizontal scrollbar, elements clipped at the right edge
+- Overlapping text/elements, or so close they read as one word; unintended truncation (`...`). `--render` catches most (line `⚠ text dính/chồng lấn` in DOM AUDIT) — only a safety net; still scan by eye, the heuristic misses non-text cases (icon over button, image over card...)
+- Broken image (empty frame/broken icon), missing icon (tofu square — usually mdi font not loaded or wrong icon name)
+- Spinner forever (v_Loading never returns to false — usually a hung API/init error)
+
+### B. Layout, alignment, spacing
+
+- **Alignment**: fields in a row share baseline and height (consistent `dense`/`outlined`); cards/blocks in a row share height
+- **Semantic alignment**: text left; **numbers/currency in tables right** (`t-num`); column header matches data alignment
+- **Button placement**: page primary action in the toolbar on the right; in a dialog the primary button (Lưu/Đồng ý) sits **right** in `v-card-actions` (pushed by `v-spacer`); no redundant "Đóng" button (D7)
+- **Toolbar row — bloated buttons / equal gaps** = columns missing `shrink`: buttons much wider than their text, **equal** gaps, trailing group **not flush right** despite `v-spacer` ⇒ columns still `flex-grow: 1`, sharing free space like the spacer. Standard: **every column `"col": "shrink"` except `v-spacer`** — including empty-`w` columns ([controls-patterns.md](controls-patterns.md) §Toolbar row). `fui module validate` catches this before any screenshot
+- **Consistent spacing**: Vuetify rhythm (multiples of 4px — pa-2/ma-2...); no abnormally large gaps between blocks, no blocks touching the screen edge
+- **Data tables**: scroll ONLY inside the table (main table declares `":height": -16`), no two nested vertical page scrollbars, table header stays visible on scroll (D9)
+- **Grid balance**: sensible column ratios in a row (Σw ≤ 12), no column squeezed so narrow content wraps badly
+
+### C. Color & visual hierarchy (App-mode vs `fui design read fui`)
+
+- Validator rules D1–D9: dialog toolbar **same background** as body (no color/dark); delete button **warning orange** (not red/error); dialog width in 400/550/600/650/800
+- 1–2 accent colors per screen; no arbitrary color on cards/secondary buttons
+- Readable contrast (light grey on white, text on colored backgrounds — report if doubtful)
+- Status (chip/badge) semantic colors consistent: success/warning/error mean the same everywhere
+
+### D. Density & responsive
+
+- Consistent `dense`/compact level across the screen (no dense-here, sparse-there)
+- Mobile image: columns wrap correctly, buttons don't overflow and aren't too small to tap, readable font, tables have a mobile plan (`mobile-breakpoint`)
+- `viewport-fit=cover` (FUI default): content at top/bottom edges on notched screens → needs safe-area padding
+
+---
+
+## Symptom → common cause
+
+| Symptom                                   | Common cause                                                                          | Fix                                                                                |
+| ----------------------------------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| Page has vertical scroll, endless table   | f-table/f-sheet without `:height` → grows with row count                              | Add `":height": -16` (measures `rect.top`, fills to bottom)                        |
+| Table short/overflowing by a fixed amount | Old hand-computed `:height` `"$( window ).height()-N"` doesn't match the real toolbar | Replace with `":height": -16`                                                      |
+| Form fields of uneven height              | Mixed with/without `dense`, `hide-details`                                            | Use `outlined dense hide-details` across the form                                  |
+| Numbers left-aligned in table             | Column missing `el: "t-num"` / align                                                  | See `component-table.md`                                                           |
+| Blank chart                               | Container 0-height at chart init                                                      | Give the container a concrete `:height`; `--render` audit "canvas 0-size" confirms |
+| Square icon                               | Wrong `mdi-*` name or font not loaded                                                 | Check icon name; import materialdesignicons                                        |
+| Dialog overflowing / tiny                 | Non-standard width                                                                    | Widths 400/550/600/650/800 (D3)                                                    |
+| Primary button left in dialog             | Missing `v-spacer` in v-card-actions                                                  | Add v-spacer before the primary button                                             |
+| Block touching screen edge                | Missing page-container / pa-*                                                         | See `ui-layout-patterns.md`                                                        |
+
+---
+
+## FUI default meta viewport (affects UI)
+
+FUI pages already include in `<head>` (do NOT repeat in header.html):
+
+```html
+<meta charset="UTF-8" />
+<meta
+  name="viewport"
+  content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no, viewport-fit=cover"
+/>
+```
+
+Consequences:
+
+- `user-scalable=no, maximum-scale=1` — **no pinch-zoom** → fonts/buttons must be large enough on mobile from the start.
+- `width=device-width, initial-scale=1` — layout in true device CSS pixels; Vuetify breakpoints work normally.
+- `viewport-fit=cover` — page extends into iOS notch/home-indicator → content at top/bottom edges needs `env(safe-area-inset-*)` padding for fullscreen/HTMLOnly.