@fui-org/fui-cli 1.2.1 → 1.3.2

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

@@ -0,0 +1,163 @@
+# Watcher Patterns
+
+> Owns: **`watch`: `v_old`, deep-watch, cascading, race control**. Action syntax: [controls-patterns.md](controls-patterns.md).
+
+Use for multi-level dependent forms (Province → District → Ward) and attribute filters (status, type, date, keyword...). Goals: correct FUI structure (`data`, `watch`, `controls`, `set`), no watcher loops, fewer redundant API calls, maintainable large modules.
+
+## 1. Rules
+
+1. **Watch the smallest input key** — an ID or filter field (`provinceID`, `districtID`, `filter.status`), not a large object unless needed.
+2. **Split actions by level** — `handleProvinceChange` only resets dependents and calls `apiLoadDistricts`; `handleDistrictChange` only resets the level below and calls `apiLoadWards`; `applyFilters` holds the final list-loading logic.
+3. **`deep-watch` selectively** — only small filter objects (e.g. `filter`). Never deep-watch large arrays like `items`, `tableData`.
+4. **No self-made loops** — never watch the action's own output var; never watch `items` and write `items` in the callback.
+5. **Guard before API calls** — `IF/THEN/ELSE` to validate input (e.g. no province selected → don't load districts).
+6. **Debounce/race control in `script.js`** — watchers only orchestrate; debounce and stale-response-overwrite protection live in JS helpers.
+7. **Force literal strings only via `IN`** — in an action with `IN`, a string without spaces may be read as an expression → use `` `value`` or `"'value'"`. Full rules: [controls-patterns.md §0](controls-patterns.md#0-value-resolution-rules-fundamental).
+
+## 2. Pattern A: administrative-area cascade
+
+```json
+{
+  "data": [
+    {
+      "formData": {
+        "provinceID": null,
+        "districtID": null,
+        "wardID": null
+      },
+      "provinceList": [],
+      "districtList": [],
+      "wardList": []
+    },
+    {
+      "apiLoadProvinces": {
+        "API": "/api/location/provinces",
+        "OUT": "provinceList"
+      },
+      "apiLoadDistricts": {
+        "API": "/api/location/districts",
+        "IN": { "ProvinceID": "formData.provinceID" },
+        "OUT": "districtList"
+      },
+      "apiLoadWards": {
+        "API": "/api/location/wards",
+        "IN": { "DistrictID": "formData.districtID" },
+        "OUT": "wardList"
+      }
+    },
+    {
+      "handleProvinceChange": [
+        {
+          "districtList": [],
+          "wardList": [],
+          "formData.districtID": null,
+          "formData.wardID": null
+        },
+        {
+          "IF": "formData.provinceID",
+          "THEN": { "CALL": "apiLoadDistricts" }
+        }
+      ],
+      "handleDistrictChange": [
+        {
+          "wardList": [],
+          "formData.wardID": null
+        },
+        {
+          "IF": "formData.districtID",
+          "THEN": { "CALL": "apiLoadWards" }
+        }
+      ]
+    },
+    {
+      "CALL": "apiLoadProvinces"
+    }
+  ],
+  "watch": {
+    "formData.provinceID": { "CALL": "handleProvinceChange" },
+    "formData.districtID": { "CALL": "handleDistrictChange" }
+  }
+}
+```
+
+Key points: watch specific keys; reset lower levels before calling their API; guard against calling with null.
+
+## 3. Pattern B: filter object + deep-watch
+
+```json
+{
+  "data": [
+    {
+      "filter": {
+        "keyword": "",
+        "status": null,
+        "fromDate": null,
+        "toDate": null
+      },
+      "items": []
+    },
+    {
+      "apiLoadItems": {
+        "API": "/api/items/search",
+        "IN": {
+          "Keyword": "filter.keyword",
+          "Status": "filter.status",
+          "FromDate": "filter.fromDate",
+          "ToDate": "filter.toDate"
+        },
+        "OUT": "items"
+      }
+    },
+    {
+      "handleFilterChanged": {
+        "CALL": "apiLoadItems"
+      }
+    }
+  ],
+  "watch": {
+    "deep-watch": {
+      "filter": { "CALL": "handleFilterChanged" }
+    }
+  }
+}
+```
+
+Keep `filter` small and stable. Continuous text-search input → debounce in `script.js`.
+
+## 4. Recommended debounce (script.js)
+
+```javascript
+var filterTimer = null;
+
+function debounceFilter(input) {
+  var callActionName = input && input.callActionName;
+  var waitMs = input && input.waitMs;
+  clearTimeout(filterTimer);
+  filterTimer = setTimeout(function () {
+    CALL(vueData[callActionName]);
+  }, waitMs || 350);
+}
+```
+
+Action in `module.json`:
+
+```json
+{
+  "handleFilterChanged": {
+    "FUN": "debounceFilter",
+    "IN": {
+      "callActionName": "'apiLoadItems'",
+      "waitMs": 350
+    }
+  }
+}
+```
+
+## 5. Watcher QA checklist
+
+1. Watch key small enough (ID/field, not a large object)?
+2. Dependents reset before calling the API?
+3. `IF` guard before API when input is null/empty?
+4. Any watcher loop risk?
+5. Text input needs debounce?
+6. Action with `IN`: literal string rule applied to space-free text values?

package/skills/fui-skill-cli/references/websocket-realtime.md

@@ -0,0 +1,271 @@
+# FUI Real-time Messaging — WebSocket (SignalR)
+
+> Owns: **real-time/SignalR: `webSocketJoinGroup`, `webSocket_Send`**.
+
+Real-time uses **SignalR** (not the browser WebSocket API), hosted at `ws.fui.vn`. Client logic is already global in `defaultfunction.js` — do not rewrite it. Declare the right structure in `module.json` and use the 3 built-ins: `webSocketConnection`, `webSocketJoinGroup`, `webSocket_Send`.
+
+---
+
+## 1. Required imports
+
+Add 2 JS files with `fui import new` — **in this order** (second depends on first):
+
+| Order           | File                                                    | Note                                                               |
+| --------------- | ------------------------------------------------------- | ------------------------------------------------------------------ |
+| 1 (lower sort)  | `https://ws.fui.vn/Scripts/jquery.signalR-2.4.1.min.js` | SignalR client core                                                |
+| 2 (higher sort) | `https://ws.fui.vn/signalr/hubs`                        | Server-generated hub proxy — JS content despite no `.js` extension |
+
+```bash
+fui import new --type .js --content-type link --name "https://ws.fui.vn/Scripts/jquery.signalR-2.4.1.min.js" --sort 100
+fui import new --type .js --content-type link --name "https://ws.fui.vn/signalr/hubs" --sort 110
+```
+
+See `fui import new --help`.
+
+> jQuery is already in the FUI runtime — do not import it. Run `fui import list` first to avoid duplicates (same flow as `f-echart` in [components-echart.md](components-echart.md)).
+
+---
+
+## 2. Auto-connect on module load
+
+FUI bootstrap (`buildApp` in `fastproject.js`) checks `vueData.webSocket` right after `data[]` runs:
+
+- If `vueData.webSocket` exists → creates `vueData.webSocketState = { code, text }` and calls `webSocketConnection('https://ws.fui.vn/signalr', vueData.webSocket, vueData.webSocketState)` + `webSocketJoinGroup(vueData.webSocket)`. **Do not call these yourself at bootstrap** — just declare `webSocket` in `data[]`.
+- `webSocketState.text`: `Reconnecting` / `Connected` / `Disconnected`. Bind to UI for debugging (`innerHTML: "{{webSocketState}}"`).
+
+---
+
+## 3. Declare groups to join — in `data[]`
+
+```json
+"data": [
+  {
+    "TenNhomDong": "`ThuNha",
+    "DGroup": "`device-abc",
+    "webSocket": {
+      "nhom1": [],
+      "nhom2": null,
+      "{{DGroup}}": {}
+    }
+  }
+]
+```
+
+- Each **key** of `webSocket` = a group joined on load.
+- **Value type sets receive behavior:**
+  - **array** (`[]`) → new messages **pushed** to the end (history: chat log, event list...).
+  - **`null` or object** (`{}`) → new message **overwrites** (latest only: status/counter/single notification).
+- Group name: literal (`nhom1`) or **dynamic via `{{ }}` in the key** — `"{{DGroup}}"` resolves to `DGroup`'s current value (e.g. `device-abc`), for per-user/device groups.
+- `` `ThuNha `` / `` `device-abc `` use backtick to force a literal string — see [Value Resolution Rules](controls-patterns.md#0-value-resolution-rules-fundamental).
+
+---
+
+## 4. Join more groups at runtime — `FUN: webSocketJoinGroup`
+
+Join any time, including as an auto-run action in `data[]` (see [ui-patterns.md §1](ui-patterns.md)):
+
+```json
+{
+  "FUN": "webSocketJoinGroup",
+  "IN": {
+    "Nhom3": null,
+    "{{TenNhomDong}}": []
+  }
+}
+```
+
+- `IN` **is the `groupObj`** (first param of `webSocketJoinGroup(groupObj, timeout, callBackFunc)`), not mapped by param name. So `FUN` + `IN` **cannot pass `timeout`/`callBackFunc`** — for those use raw `EXE`: `"EXE": "webSocketJoinGroup({Nhom3:null}, 3000, function(){ ... })"`.
+- Use for groups that are **conditional** or known only **after** load (e.g. after an API returns a room/chat ID), instead of static `webSocket: {}`.
+
+---
+
+## 5. Receive messages
+
+### watch (recommended — run logic on new message)
+
+```json
+"watch": {
+  "webSocket.nhom1": { "MESS": "thong bao" },
+  "webSocket.device-abc": { "MESS": "thong bao" }
+}
+```
+
+> **Important:** `watch` keys **cannot** use `{{ }}` (literal, not interpolated) — write the resolved group (`webSocket.device-abc`, not `webSocket.{{DGroup}}`).
+
+### Bind directly to UI (raw, no watch)
+
+```json
+{
+  "el": "v-textarea",
+  "attr": { "v-model": "webSocket.nhom2", "label": "Nội dung nhận nhom2", "rows": 5 }
+}
+```
+
+### Debug all state
+
+```json
+{ "el": "div", "attr": {}, "innerHTML": "{{webSocket}}" }
+```
+
+---
+
+## 6. Send — `webSocket_Send`
+
+`webSocket_Send(obj)` takes **one object** `{ group, data }`; `data` may be object, array or string — the function picks the SignalR API (`messageSendObject` / `messageSendArray` / `messageSend`).
+
+### Way 1 — `FUN` + `IN` (object payload)
+
+```json
+{
+  "FUN": "webSocket_Send",
+  "IN": {
+    "group": "`nhom1",
+    "data": { "text": "doi tuong 1", "text2": "doi tuong 2" }
+  }
+}
+```
+
+### Way 2 — raw `EXE` (read dynamic vueData values)
+
+```json
+{ "EXE": "webSocket_Send({ group:'nhom2', data:vueData.messText })" }
+```
+
+### Way 3 — array payload
+
+```json
+{
+  "FUN": "webSocket_Send",
+  "IN": { "group": "`nhom3", "data": ["mang 1", "mang 2"] }
+}
+```
+
+### Directly in `script.js` (outside the action engine)
+
+```js
+webSocket_Send({ group: "Nhom3", data: "Gui noi dung từ JS" });
+```
+
+### Way 4 — HTTP API (no client SignalR connection needed)
+
+REST endpoint to send to a group:
+
+```json
+{
+  "API": "https://ws.fui.vn/api/messageSend/nhom1",
+  "IN": { "text": "test 1", "text2": "test 2" }
+}
+```
+
+Group name interpolates in the URL:
+
+```json
+{ "API": "https://ws.fui.vn/api/messageSend/{{DGroup}}" }
+```
+
+Use when `FUN`/`EXE` is inconvenient (e.g. server-side sends, or decoupling sending from whether the client holds a SignalR connection).
+
+---
+
+## 7. Full example
+
+```json
+{
+  "data": [
+    {
+      "TenNhomDong": "`ThuNha",
+      "DGroup": "`device-abc",
+      "webSocket": { "nhom1": [], "nhom2": null, "{{DGroup}}": {} }
+    },
+    {
+      "FUN": "webSocketJoinGroup",
+      "IN": { "Nhom3": null, "{{TenNhomDong}}": [] }
+    }
+  ],
+  "watch": {
+    "webSocket.nhom1": { "MESS": "thong bao" },
+    "webSocket.device-abc": { "MESS": "thong bao" }
+  },
+  "controls": [
+    {
+      "prop": "fluid grid-list-md",
+      "rows": [
+        {
+          "prop": "",
+          "cols": [
+            {
+              "el": "v-textarea",
+              "col": { "class": "" },
+              "attr": { "v-model": "messText", "label": "noi dung", ":required": false, "rows": 5 },
+              "w": ""
+            },
+            {
+              "el": "f-button",
+              "col": { "class": "shrink" },
+              "attr": {
+                "label": "send - nhom2",
+                ":action": [
+                  {
+                    "FUN": "webSocket_Send",
+                    "IN": { "group": "`nhom1", "data": { "text": "doi tuong 1", "text2": "doi tuong 2" } }
+                  },
+                  { "EXE": "webSocket_Send({ group:'nhom2', data:vueData.messText})" },
+                  { "FUN": "webSocket_Send", "IN": { "group": "`nhom3", "data": ["mang 1", "mang 2"] } }
+                ]
+              }
+            }
+          ]
+        },
+        {
+          "prop": "",
+          "cols": [
+            {
+              "el": "v-textarea",
+              "col": {},
+              "attr": { "v-model": "webSocket.nhom2", "label": "Nội dung nhận nhom2", ":required": false, "rows": 5 }
+            }
+          ]
+        },
+        { "prop": "", "cols": [{ "el": "div", "col": {}, "attr": {}, "innerHTML": "{{webSocket}}" }] },
+        {
+          "prop": "",
+          "cols": [
+            {
+              "el": "f-button",
+              "col": {},
+              "attr": {
+                "label": "send by API - nhom1",
+                ":action": [
+                  { "API": "https://ws.fui.vn/api/messageSend/nhom1", "IN": { "text": "test 1", "text2": "test 2" } }
+                ]
+              }
+            },
+            {
+              "el": "f-button",
+              "col": {},
+              "attr": {
+                ":label": "'send by API - ' + DGroup",
+                ":action": [{ "API": "https://ws.fui.vn/api/messageSend/{{DGroup}}" }]
+              }
+            }
+          ]
+        },
+        { "prop": "", "cols": [{ "el": "div", "col": {}, "attr": {}, "innerHTML": "{{webSocketState}}" }] }
+      ]
+    }
+  ],
+  "set": {}
+}
+```
+
+---
+
+## 8. Checklist
+
+- [ ] `fui import list`: are `jquery.signalR-2.4.1.min.js` + `signalr/hubs` present?
+- [ ] Missing → `fui import new` both, sort order signalR first, hubs second
+- [ ] Declare `data[].webSocket = { groupName: [] | null | {} }` — value type by need (history vs latest)
+- [ ] Runtime/conditional groups → `FUN: webSocketJoinGroup` (no `timeout`/`callBackFunc` via `IN`; use `EXE` if needed)
+- [ ] Receive: `watch` (literal key, no `{{ }}`) or bind `v-model="webSocket.<group>"`
+- [ ] Send: `FUN: webSocket_Send` (object/array), `EXE` for dynamic `vueData`, or `API: https://ws.fui.vn/api/messageSend/<group>` for HTTP instead of client SignalR
+- [ ] Use `vueData.webSocketState` if the user needs to see connection status