@fui-org/fui-cli 1.2.1 → 1.3.1

package/skills/fui-skill-cli/references/component-table.md

@@ -0,0 +1,248 @@
+# FUI Table Components (Source-Based)
+
+> Owns: **`f-table` in depth: all props, auto-header, `sum-format`, readonly table**. In-cell controls (`t-*`): [ui-table-cell-patterns.md](ui-table-cell-patterns.md).
+
+Source: `scripts/componentTable.js` (V2), `scripts/componentTable-3.0.js` (V3).
+
+> **Check the version before writing headers** — V2/V3 field names differ; wrong names = no render. See "V2 vs V3" below.
+
+> `f-table` does CRUD and readonly. Readonly = no `:update-api` (or `:disabled-update true`); omit `:headers` to auto-build.
+
+## Prefix Reminder
+
+`f-table` = FUI component · `t-*` = FUI cell renderers · `v-data-table` = Vuetify internals (CRUD/action flow comes from FUI wrappers).
+
+## f-table
+
+### Props (exact from source)
+
+`value`, `headers`, `updateForm`, `updateFormAttr`, `updateApi`, `items`, `label`, `excel`, `showSearch`, `sumFormat`, `disabledHover`, `returnObject`, `itemKey`, `itemsPerPage`, `disabledUpdate`, `hideDefaultFooter`, `template`, `headercomponent`, `height`, `fixedHeader`, `fixedCols`
+
+### Real Behavior
+
+1. Header item with `el` → custom slot renderer created automatically.
+2. `updateApi.new` or `updateApi['new-action']` present → add button appears.
+3. CRUD action slots rely on header `value: "ctrl-update"`.
+4. Edit dialog is `f-dialog` with `updateForm`.
+5. Selection emit: `returnObject=false` → array of `itemKey`; `returnObject=true` → selected row objects.
+6. Row events from slots: `click:row`, `mouseover:row`, `mouseleave:row`.
+7. **Auto headers**: no `:headers` → built from `items` (see Auto Headers).
+8. **Sum row / sum line**: `sum-format` takes a string OR object — rendered differently (see sum-format).
+
+### Fixed left columns (`fixed-cols`)
+
+`fixed-cols="N"` keeps the first N columns during horizontal scroll. V2 and V3. Omitted, `0`, or invalid → normal behavior.
+
+```json
+{
+  "el": "f-table",
+  "w": 12,
+  "attr": {
+    ":items": "dsNhanVien",
+    "fixed-cols": "2",
+    ":headers": [
+      { "text": "Mã", "value": "Ma", "width": "100px" },
+      { "text": "Họ tên", "value": "HoTen", "width": "220px" },
+      { "text": "Phòng ban", "value": "PhongBan", "width": "180px" }
+    ]
+  }
+}
+```
+
+- Set `width` on each fixed column; missing → `150px`.
+- Numeric `width` = pixels; CSS strings like `"120px"` kept as-is.
+- `fixed-cols` counts actual rendered columns; Vuetify select/group columns, if enabled, are counted.
+- CSS is scoped per `f-table` instance, so several tables with different fixed counts can share a page.
+
+### Auto Headers (no `:headers`)
+
+With `:headers` omitted, `f-table` builds headers from the first row of `items` (via `buildHeader`):
+
+- Each key → column `{ text: key, value: key, divider: true }`; numeric values → `el: "t-num"` (right-aligned number format).
+- `:update-api` with `edit`/`delete` and no `disabled-update` → `ctrl-update` column appended.
+- Rebuilt whenever `items` changes shape (watch on `items`) — safe with async loads.
+
+**Use when** columns = API fields exactly (SP aliases nice Vietnamese names). **Declare `:headers` when** labels differ from fields, columns hidden, custom `t-*` (t-time, t-check, t-link...), specific width/align, or technical fields (internal IDs, flags) must not show.
+
+```json
+{ "el": "f-table", "w": "12", "attr": { "label": "Kết quả", ":items": "dsKetQua", "show-search": true } }
+```
+
+### sum-format — column totals (2 forms)
+
+**Form 1 — string template → ONE total text line below the table** (in `v-card-actions`, NOT inside `v-data-table`, not column-aligned):
+
+```json
+"sum-format": "Tổng đăng ký: [[DangKy]] | Nhập học: [[NhapHoc]]"
+```
+
+- `[[FieldName]]` → `_.sumBy(items, 'FieldName')`, fixed format `'0,0'` (numeral).
+- Single right-aligned text line below the table (separated by `v-divider`).
+- For one summary line / several totals in one sentence.
+- Static string → attr WITHOUT `:` prefix.
+
+**Form 2 — object → REAL total row inside the table** (`v-data-table` slot `body.append`, aligned per column):
+
+```json
+":sum-format": { "DangKy": "0,0", "NhapHoc": "0,0", "HocPhi": "0,0.0" }
+```
+
+- Key = column `value` in headers; value = numeral format for that column (`"0,0"`, `"0,0.0"`, `"0.0%"`, ...).
+- Renders a final `<tr>`: cells whose column key is in the object show `_.sumBy(items, key)` in that format; others empty. All cells right-aligned, `font-weight-medium`.
+- Aligned with columns, scrolls with the body.
+- Object → attr WITH `:` prefix.
+
+**Choosing:** "total row under each column / total row in table / column-aligned totals" → object. "General summary text line" → string. **NEVER build a total row manually** (no pushing a "Tổng" row into items, no hand-written body.append template) — use `sum-format`.
+
+Full object example:
+
+```json
+{
+  "el": "f-table",
+  "w": "12",
+  "attr": {
+    "label": "Thống kê tuyển sinh",
+    ":items": "dsThongKe",
+    ":headers": [
+      { "text": "Ngành", "value": "TenNganh" },
+      { "text": "Đăng ký", "value": "DangKy", "el": "t-num" },
+      { "text": "Nhập học", "value": "NhapHoc", "el": "t-num" }
+    ],
+    ":sum-format": { "DangKy": "0,0", "NhapHoc": "0,0" }
+  }
+}
+```
+
+### updateApi Keys Used By Source
+
+`new`, `edit`, `delete`, `default-item`, `new-action`, `edit-action`, `data-out`
+
+### Minimal CRUD Example
+
+```json
+{
+  "el": "f-table",
+  "w": "12",
+  "attr": {
+    "label": "Danh sach nhan vien",
+    ":items": "items",
+    "item-key": "ID",
+    ":return-object": false,
+    "show-search": true,
+    "excel": true,
+    ":headers": [
+      { "text": "Ho ten", "value": "FullName" },
+      { "text": "Email", "value": "Email" },
+      { "text": "Trang thai", "value": "Active", "el": "t-boolean", "align": "center", "width": "90px" },
+      { "text": "Tac vu", "value": "ctrl-update", "align": "center", "width": "120px" }
+    ],
+    ":update-form": [
+      { "el": "v-text-field", "attr": { "v-model": "FullName", "label": "Ho ten", ":required": true } },
+      { "el": "v-text-field", "attr": { "v-model": "Email", "label": "Email", ":required": true } }
+    ],
+    ":update-api": {
+      "default-item": { "FullName": "", "Email": "", "Active": true },
+      "new": {
+        "API": "/api/staff/create",
+        "IN": { "FullName": "item.FullName", "Email": "item.Email", "Active": "item.Active" },
+        "CALLBACK": { "CALL": "apiLoadItems" }
+      },
+      "edit": {
+        "API": "/api/staff/update",
+        "IN": { "ID": "item.ID", "FullName": "item.FullName", "Email": "item.Email", "Active": "item.Active" },
+        "CALLBACK": { "CALL": "apiLoadItems" }
+      },
+      "delete": {
+        "CONFIRM": "Xac nhan xoa?",
+        "API": "/api/staff/delete",
+        "IN": { "ID": "item.ID" },
+        "CALLBACK": { "CALL": "apiLoadItems" }
+      }
+    }
+  }
+}
+```
+
+## Readonly Table
+
+`f-table` without `:update-api` (no add/edit/delete buttons); omit `:headers` to auto-build:
+
+```json
+{
+  "el": "f-table",
+  "w": "12",
+  "attr": {
+    "label": "Danh sach xem nhanh",
+    ":items": "items",
+    "item-key": "ID",
+    "show-search": true,
+    "excel": true,
+    ":items-per-page": 20
+  }
+}
+```
+
+## t-* Cell Renderers
+
+Set `el` in `headers`:
+
+```json
+{ "text": "Ngay tao", "value": "CreatedAt", "el": "t-time", "attr": { "format": "DD/MM/YYYY HH:mm" } }
+```
+
+Supported: `t-html`, `t-label`, `t-num`, `t-time`, `t-boolean`, `t-check`, `t-text`, `t-select`, `t-combobox`, `t-menu`, `t-link`, `t-button`
+
+### Notes
+
+1. Editable renderers (`t-check`, `t-text`, `t-select`, `t-combobox`, `t-menu`, `t-button`) use `tableActionEvent`.
+2. Opening a dialog from a row action: `target: "dialog"` plus `wid`, `url`, `title`, `onclose`.
+3. Literal-string rule applies only in Action `IN` mapping. Static props without `:` are plain strings by default.
+
+---
+
+## V2 vs V3 (source: `componentTable.js` vs `componentTable-3.0.js`)
+
+Framework version comes from `_projectInfo.json` or `_moduleInfo.json` — check before writing headers.
+
+### Header field names
+
+**Most common mistake.** V2 `text`/`value` are renamed `title`/`key` in V3:
+
+| Field        | V2 (`componentTable.js`) | V3 (`componentTable-3.0.js`) |
+| ------------ | ------------------------ | ---------------------------- |
+| Column label | `"text": "Tên cột"`      | `"title": "Tên cột"`         |
+| Data field   | `"value": "TenField"`    | `"key": "TenField"`          |
+| Ctrl column  | `"value": "ctrl-update"` | `"key": "ctrl-update"`       |
+
+```json
+// V2 ✅
+{ "text": "Họ tên", "value": "HoTen", "el": "t-label" }
+{ "text": "Tác vụ", "value": "ctrl-update", "align": "center" }
+
+// V3 ✅
+{ "title": "Họ tên", "key": "HoTen", "el": "t-label" }
+{ "title": "Tác vụ", "key": "ctrl-update", "align": "center" }
+```
+
+> `text`/`value` on V3 → columns render but **headers vanish, sort breaks** (Vuetify 3 ignores them). No JS error — only visible in a rendered screenshot.
+
+### Extra V3 props
+
+| Prop             | V3 default  | Note                                                                     |
+| ---------------- | ----------- | ------------------------------------------------------------------------ |
+| `density`        | `'compact'` | Row density — `'compact'`/`'comfortable'`/`'default'`                    |
+| `disable-sort`   | `false`     | Disable sorting for the whole table                                      |
+| `slots`          | `null`      | Dynamic custom slots (object `{ name, html }`)                           |
+| `group-template` | `null`      | Template for groups (`groupBy`)                                          |
+| `height`         | `null`      | Same as V2: null/omitted = auto-grow; ≤0 = fill to bottom; >0 = fixed px |
+
+### sum-format object in V3
+
+In V3 the `sum-format` object keys must match header `key` (not `value`):
+
+```json
+// V3 ✅ — key = "DangKy" khớp với header { "key": "DangKy" }
+":sum-format": { "DangKy": "0,0", "NhapHoc": "0,0" }
+```
+
+Otherwise identical to V2.

package/skills/fui-skill-cli/references/components-dialog.md

@@ -0,0 +1,191 @@
+# FUI Dialog & Overlay Components
+
+> Owns: **`f-dialog`, `f-window`, `f-editor`**. Hand-built dialog pattern (`v-dialog` + hidden-container): [ui-dialog-patterns.md](ui-dialog-patterns.md).
+
+Dialog, overlay and content-editor components. Prefix/binding rules: [components-display.md](components-display.md).
+
+## f-window
+
+- Props (source): `id`
+- Internal iframe dialog host, usually opened via `openWindow(...)`
+
+```json
+{
+  "FUN": "openWindow",
+  "IN": {
+    "id": "`winUser",
+    "url": "'/fp/module?mid=123'",
+    "title": "Chi tiet user",
+    "width": 1100
+  }
+}
+```
+
+## f-editor
+
+- Props (source): `value`, `imageapi`, `height`, `toolbar`
+- Emit: `input` with HTML content
+- Wraps CKEditor with upload auth header
+
+```json
+{
+  "el": "f-editor",
+  "w": "12",
+  "attr": {
+    "v-model": "formData.contentHtml",
+    "imageapi": "/api/editor/upload",
+    ":height": 360
+  }
+}
+```
+
+## f-editor-dialog
+
+- Props (source): `value`, `imageapi`, `label`, `width`, `toolbar`
+- `value` must be an object (`open`, `text`, `object`, `ok`), not a plain string
+- Modal editor, writes back on OK
+
+```json
+{
+  "el": "f-editor-dialog",
+  "w": "6",
+  "attr": {
+    ":value": "editorState",
+    "label": "Noi dung mo rong",
+    ":width": 1000,
+    "imageapi": "/api/editor/upload"
+  }
+}
+```
+
+## f-dialog
+
+Modal that builds a form from a `controls` array; supports local watchers, validation and action buttons.
+
+- Props:
+  - `value` (Boolean, default `false`) — v-model open/close
+  - `data` (Object, default `{}`) — input data, bind with `:data.sync`; copied into fields when the dialog opens
+  - `dataOut` (Object, default `{}`) — output, bind with `:data-out.sync`; receives the component instance on open
+  - `title` (String, default `''`)
+  - `controls` (Array, default `[]`) — control definitions (`el`, `attr`, `w` col width); any field whose `v-model` doesn't start with `vueData.` gets local data auto-created (init `null`)
+  - `watch` (Object, default `{}`) — local watchers; key = field name, value = action run on change; registered on open, removed on close
+  - `button` (Array, default `[]`) — button definitions (below)
+  - `disableValidate` (Boolean, default `false`) — skip form validation when `true`
+  - `width` (Number, default `800`) — px
+  - `openAction` (Object, default `null`) — action run as soon as the dialog opens
+
+- Emits:
+  - `input` — open/close (v-model)
+  - `update:data-out` — component instance on open (parent can reach local data)
+  - `update:data` — `v_outData` when a button with `getoutdata: true` is clicked (after validation passes)
+
+- On open (`value = true`):
+  1. Reset all fields from `:data` (`setDefaultData`)
+  2. Register watchers from `watch`
+  3. Run `openAction` if set
+  4. Emit `update:data-out` with the instance
+
+- On close (`value = false`): remove all registered watchers.
+
+- Button object:
+  - `label` (String)
+  - `color` (String, default `"primary"`)
+  - `elevation` (Number, default `0`)
+  - `text` (Boolean, default `true`) — text button
+  - `type` (String) — e.g. `"submit"`
+  - `:disabled` (String) — Vue expression, e.g. `"!checkBoxValue"`
+  - `v-if` (String) — Vue expression to show/hide, e.g. `"ModuleID==1"`
+  - `icon-text` (String) — MDI icon left of the label
+  - `checkvalid` (Boolean) — validate before running the action; stop if invalid
+  - `getoutdata` (Boolean) — sync field values into `v_outData` then emit `update:data`; also triggers validation
+  - `action` (Array | Function) — actions run on click; context = all `v_outData` fields plus `dData` pointing to `v_outData`
+
+- Notes:
+  - Button clicks debounced 500ms (leading edge) against double-click
+  - Controls support `br: true` for a row break
+  - Template is built statically at `data()` init; no re-render when `controls` changes
+  - In the template, `watch` is `:watch` (dynamic bind), not Vue's default `watch`
+  - **Never put `f-dialog` inside a component template:** it works only when declared directly in the module JSON `controls`; inside a Vue component it misbehaves.
+  - **Declare `vueData` variables before binding them in controls:** a control bound to `vueData.someVar` needs that variable declared in the module `data` first — Vue can't make a variable reactive if it doesn't exist at init.
+
+```json
+"data": [
+  { "projectList": [] }
+],
+"controls": [
+  {
+    "prop": "fluid pa-0",
+    "rows": [{ "prop": "", "cols": [
+      {
+        "el": "v-autocomplete",
+        "attr": {
+          "v-model": "pid",
+          "label": "Module name",
+          ":items": "vueData.projectList",
+          "item-text": "ModuleName",
+          "item-value": "ModuleID"
+        }
+      }
+    ]}]
+  }
+]
+```
+
+- Full example:
+
+```json
+{
+  "el": "f-dialog",
+  "attr": {
+    "v-model": "dialogOpen",
+    ":data.sync": "dialogData",
+    "title": "Nhap du lieu",
+    ":open-action": { "MESSBOX": "Bạn vừa mở dialog" },
+    ":controls": [
+      { "el": "v-text-field", "attr": { "v-model": "Domain", "label": "Domain" }, "w": 4 },
+      { "el": "v-text-field", "attr": { "v-model": "ModuleID", "label": "ModuleID" }, "w": 3 },
+      { "el": "v-text-field", "attr": { "v-model": "ModuleName", "label": "ModuleName" }, "w": 8 },
+      {
+        "el": "v-checkbox",
+        "attr": { ":label": "`Tôi đã hiểu và đồng ý: ${checkBoxValue}`", "v-model": "checkBoxValue" }
+      },
+      {
+        "el": "v-select",
+        "attr": {
+          "label": "select",
+          "v-model": "bienselect",
+          ":items": "vueData.Mang",
+          "item-text": "AppName",
+          "item-value": "AppListID"
+        }
+      }
+    ],
+    ":watch": {
+      "bienselect": { "MESSBOX": "Watch Select {{bienselect}}" },
+      "Domain": { "MESSBOX": "Watch textbox {{Domain}}" }
+    },
+    ":button": [
+      {
+        "label": "Submit OK",
+        "type": "submit",
+        ":disabled": "!checkBoxValue",
+        "action": [
+          { "ModuleName": "gan gia tri cho ModuleName" },
+          { "MESSBOX": "thong bao 1" },
+          { "dialogOpen": false }
+        ]
+      },
+      {
+        "label": "Chay mot API",
+        "checkvalid": true,
+        "v-if": "ModuleID==1",
+        "action": [{ "API": "/chaymotapi" }]
+      },
+      {
+        "label": "Close",
+        "action": [{ "dialogOpen": false }]
+      }
+    ]
+  }
+}
+```

package/skills/fui-skill-cli/references/components-display.md

@@ -0,0 +1,141 @@
+# FUI Display & Presentation Components
+
+> Owns: **display components: `f-label`, `f-title`, `f-box`, `f-header`, `f-slider`, chip/badge**.
+
+Components for showing info, charts, media. Also holds prefix/binding rules for all f-* components.
+
+## Prefix and binding rules
+
+- `f-*`: FUI components (FUI runtime)
+- `v-*`: Vuetify components
+- `uc-*`: custom module components from `components/`
+- In `module.json`, pass props via `attr`
+- Kebab-case in JSON for custom props (`api-upload`, `item-value`)
+- Dynamic values use `:prop`
+- Use `v-on:*` in JSON (not `@*`)
+- Props without `:` (e.g. `url`, `api-upload`) are plain strings by default
+- Literal-string forcing (backtick/quote) only in Action `IN` mappings, never for static props
+
+## Minimal control pattern
+
+```json
+{
+  "el": "f-date",
+  "w": "6",
+  "attr": {
+    "v-model": "formData.fromDate",
+    "label": "From date"
+  }
+}
+```
+
+---
+
+## f-label
+
+- Props (source): `items`, `text`, `color`, `iconText`
+- Renders `v-chip` from `text` and/or `items`
+
+```json
+{
+  "el": "f-label",
+  "w": "12",
+  "attr": {
+    "text": "Trang thai",
+    "icon-text": "mdi-information"
+  }
+}
+```
+
+## f-box
+
+- Props (source): `rowFormat`, `items`, `label`, `edit`, `saveclick`
+- Emits `input` when internal data changes
+- Displays/edits key-value rows; auto-builds row format from data if missing
+- `rowFormat`: array of `{ text, value, noEdit }` — `noEdit: true` locks that column when `edit=true`
+- `items`: object or array; an object is auto-wrapped into a 1-element array
+
+```json
+{
+  "el": "f-box",
+  "w": "12",
+  "attr": {
+    "label": "Thong tin",
+    ":items": "detailData",
+    ":edit": "isEditMode",
+    ":row-format": [
+      { "text": "Mã", "value": "StudentID", "noEdit": true },
+      { "text": "Họ tên", "value": "FullName" },
+      { "text": "Ngày sinh", "value": "BirthDate" }
+    ]
+  }
+}
+```
+
+## f-header
+
+- Props (source): `label`
+
+```json
+{
+  "el": "f-header",
+  "w": "12",
+  "attr": { "label": "Bao cao tong hop" }
+}
+```
+
+## f-title
+
+- Props (source): `label`
+
+```json
+{
+  "el": "f-title",
+  "w": "12",
+  "attr": { "label": "Danh sach ho so" }
+}
+```
+
+## f-slider
+
+- Props (source): `items`, `itemAttr`
+- Wraps `v-carousel` and `v-carousel-item`
+
+```json
+{
+  "el": "f-slider",
+  "w": "12",
+  "attr": {
+    ":items": "slideItems",
+    ":item-attr": { "contain": true }
+  }
+}
+```
+
+## f-echart
+
+→ See [`components-echart.md`](components-echart.md) — props, config, global `FEchartFormatter` module, examples.
+
+## f-pdfmake
+
+- Props (source): `data`
+- Renders PDF in an iframe; re-renders when `data` changes (deep watch)
+
+```json
+{
+  "el": "f-pdfmake",
+  "w": "12",
+  "attr": {
+    ":data": "pdfDefinition",
+    "height": "550"
+  }
+}
+```
+
+---
+
+## Practical notes
+
+1. Most `f-*` components forward unknown attrs via `v-bind="$attrs"` — Vuetify attrs still work when the child is a Vuetify control.
+2. The literal-string rule applies only to API/path strings in Action `IN` mappings.
+3. See `references/component-table.md` for `f-table`.