@fui-org/fui-cli 1.3.2 → 2.0.0

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

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

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