@fui-org/fui-cli 1.3.2 → 2.1.0

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

@@ -1,14 +1,13 @@
 # FUI Dialog & Overlay Components
 
-> File này sở hữu: **`f-dialog`, `f-window`, `f-editor`**. Pattern dialog thủ công (`v-dialog` + hidden-container) xem [ui-dialog-patterns.md](ui-dialog-patterns.md).
+> Owns: **`f-dialog`, `f-window`, `f-editor`**. Hand-built dialog pattern (`v-dialog` + hidden-container): [ui-dialog-patterns.md](ui-dialog-patterns.md).
 
-Components liên quan đến dialog, overlay, và editor nội dung. Xem prefix/binding rules tại [components-display.md](components-display.md).
+Dialog, overlay and content-editor components. Prefix/binding rules: [components-display.md](components-display.md).
 
 ## f-window
 
 - Props (source): `id`
-- Behavior: internal iframe dialog host, thường được mở qua `openWindow(...)`
-- Example:
+- Internal iframe dialog host, usually opened via `openWindow(...)`
 
 ```json
 {
@@ -26,8 +25,7 @@ Components liên quan đến dialog, overlay, và editor nội dung. Xem prefix/
 
 - Props (source): `value`, `imageapi`, `height`, `toolbar`
 - Emit: `input` with HTML content
-- Behavior: wraps CKEditor with upload auth header
-- Example:
+- Wraps CKEditor with upload auth header
 
 ```json
 {
@@ -44,9 +42,8 @@ Components liên quan đến dialog, overlay, và editor nội dung. Xem prefix/
 ## f-editor-dialog
 
 - Props (source): `value`, `imageapi`, `label`, `width`, `toolbar`
-- Runtime expectation: `value` là object (`open`, `text`, `object`, `ok`), không phải plain string
-- Behavior: modal editor, write-back on OK
-- Example:
+- `value` must be an object (`open`, `text`, `object`, `ok`), not a plain string
+- Modal editor, writes back on OK
 
 ```json
 {
@@ -63,54 +60,53 @@ Components liên quan đến dialog, overlay, và editor nội dung. Xem prefix/
 
 ## f-dialog
 
-Modal dialog tự build form từ mảng `controls`, có hỗ trợ watchers cục bộ, validation, và action buttons.
+Modal that builds a form from a `controls` array; supports local watchers, validation and action buttons.
 
 - Props:
-  - `value` (Boolean, default: `false`) — v-model để mở/đóng dialog
-  - `data` (Object, default: `{}`) — dữ liệu đầu vào, bind bằng `:data.sync`; khi dialog mở dữ liệu này được copy vào các field
-  - `dataOut` (Object, default: `{}`) — dữ liệu đầu ra, bind bằng `:data-out.sync`; nhận instance component khi dialog mở
-  - `title` (String, default: `''`) — tiêu đề dialog
-  - `controls` (Array, default: `[]`) — mảng control definitions để build form; mỗi control có `el`, `attr`, `w` (col width); field nào có `v-model` không bắt đầu bằng `vueData.` sẽ được tạo data cục bộ tự động (khởi tạo `null`)
-  - `watch` (Object, default: `{}`) — watchers cục bộ trong dialog; key là tên field, value là action chạy khi field thay đổi; watchers được đăng ký khi dialog mở và hủy khi đóng
-  - `button` (Array, default: `[]`) — mảng button definitions (xem cấu trúc button bên dưới)
-  - `disableValidate` (Boolean, default: `false`) — bỏ qua form validation khi `true`
-  - `width` (Number, default: `800`) — chiều rộng dialog (px)
-  - `openAction` (Object, default: `null`) — action chạy ngay khi dialog mở
+  - `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` — mở/đóng dialog (dùng với v-model)
-  - `update:data-out` — phát ra instance component khi dialog mở (để parent truy cập data cục bộ)
-  - `update:data` — phát ra `v_outData` khi button có `getoutdata: true` được click (sau khi validation pass)
-
-- Vòng đời khi mở (`value = true`):
-  1. Reset tất cả field về giá trị từ `:data` (gọi `setDefaultData`)
-  2. Đăng ký watchers từ prop `watch`
-  3. Chạy `openAction` nếu có
-  4. Emit `update:data-out` với instance component
-
-- Vòng đời khi đóng (`value = false`):
-  1. Hủy tất cả watchers đã đăng ký
-
-- Cấu trúc button object:
-  - `label` (String) — text hiển thị trên button
-  - `color` (String, default: `"primary"`) — màu button
-  - `elevation` (Number, default: `0`) — độ nổi
-  - `text` (Boolean, default: `true`) — dạng text button
-  - `type` (String) — ví dụ `"submit"`
-  - `:disabled` (String) — biểu thức Vue để disable button, ví dụ `"!checkBoxValue"`
-  - `v-if` (String) — biểu thức Vue để ẩn/hiện button, ví dụ `"ModuleID==1"`
-  - `icon-text` (String) — icon MDI hiển thị bên trái label
-  - `checkvalid` (Boolean) — validate form trước khi chạy action; nếu không pass thì dừng
-  - `getoutdata` (Boolean) — sync field values vào `v_outData` rồi emit `update:data`; cũng trigger validation
-  - `action` (Array | Function) — danh sách actions chạy khi click; context truyền vào gồm tất cả fields trong `v_outData` và key `dData` trỏ về `v_outData`
-
-- Lưu ý:
-  - Button click được debounce 500ms (leading edge) để tránh double-click
-  - Controls hỗ trợ `br: true` để xuống hàng (row break)
-  - Template được build tĩnh lúc `data()` init, không re-render khi prop `controls` thay đổi
-  - `watch` trong prop template là `:watch` (bind động), khác với `watch` mặc định của Vue
-  - **Không dùng `f-dialog` bên trong template của component:** `f-dialog` chỉ hoạt động khi được khai báo trực tiếp trong `controls` của cấu trúc JSON module. Nếu đặt trong template của một Vue component, nó sẽ không hoạt động đúng.
-  - **Khai báo biến `vueData` trước khi dùng trong controls:** Nếu một control bind vào `vueData.someVar`, biến đó phải được khai báo trước trong `data` của module — Vue không thể thiết lập reactivity cho biến chưa tồn tại lúc init.
+  - `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": [
@@ -135,7 +131,7 @@ Modal dialog tự build form từ mảng `controls`, có hỗ trợ watchers c
 ]
 ```
 
-- Ví dụ đầy đủ:
+- Full example:
 
 ```json
 {
@@ -156,8 +152,11 @@ Modal dialog tự build form từ mảng `controls`, có hỗ trợ watchers c
       {
         "el": "v-select",
         "attr": {
-          "label": "select", "v-model": "bienselect",
-          ":items": "vueData.Mang", "item-text": "AppName", "item-value": "AppListID"
+          "label": "select",
+          "v-model": "bienselect",
+          ":items": "vueData.Mang",
+          "item-text": "AppName",
+          "item-value": "AppListID"
         }
       }
     ],

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

@@ -1,22 +1,22 @@
 # FUI Display & Presentation Components
 
-> File này sở hữu: **component hiển thị: `f-label`, `f-title`, `f-box`, `f-header`, `f-slider`, chip/badge**.
+> Owns: **display components: `f-label`, `f-title`, `f-box`, `f-header`, `f-slider`, chip/badge**.
 
-Components dùng để hiển thị thông tin, chart, media. File này cũng chứa prefix/binding rules áp dụng cho tất cả f-* components.
+Components for showing info, charts, media. Also holds prefix/binding rules for all f-* components.
 
-## Prefix và Binding Rules
+## Prefix and binding rules
 
-- `f-*`: FUI components (định nghĩa trong FUI runtime)
+- `f-*`: FUI components (FUI runtime)
 - `v-*`: Vuetify components
-- `uc-*`: Custom module components từ `components/`
-- Trong `module.json`, truyền props qua `attr`
-- Dùng kebab-case trong JSON cho custom props (`api-upload`, `item-value`)
-- Giá trị động dùng `:prop`
-- Dùng `v-on:*` trong JSON (không dùng `@*`)
-- Props không có `:` (ví dụ `url`, `api-upload`) là plain string mặc định
-- Literal-string forcing (backtick/quote) chỉ dùng trong Action `IN` mapping, không dùng cho static props
+- `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
+## Minimal control pattern
 
 ```json
 {
@@ -34,8 +34,7 @@ Components dùng để hiển thị thông tin, chart, media. File này cũng ch
 ## f-label
 
 - Props (source): `items`, `text`, `color`, `iconText`
-- Behavior: render `v-chip` từ `text` và/hoặc `items`
-- Example:
+- Renders `v-chip` from `text` and/or `items`
 
 ```json
 {
@@ -51,11 +50,10 @@ Components dùng để hiển thị thông tin, chart, media. File này cũng ch
 ## f-box
 
 - Props (source): `rowFormat`, `items`, `label`, `edit`, `saveclick`
-- Emit: `input` khi dữ liệu nội bộ thay đổi
-- Behavior: hiển thị/chỉnh sửa key-value rows, tự build row format từ data nếu thiếu
-- `rowFormat`: mảng `{ text, value, noEdit }` — `noEdit: true` khóa cột đó khi `edit=true`
-- `items`: object hoặc array; object tự động wrap thành array 1 phần tử
-- Example:
+- 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
 {
@@ -77,7 +75,6 @@ Components dùng để hiển thị thông tin, chart, media. File này cũng ch
 ## f-header
 
 - Props (source): `label`
-- Example:
 
 ```json
 {
@@ -90,7 +87,6 @@ Components dùng để hiển thị thông tin, chart, media. File này cũng ch
 ## f-title
 
 - Props (source): `label`
-- Example:
 
 ```json
 {
@@ -103,8 +99,7 @@ Components dùng để hiển thị thông tin, chart, media. File này cũng ch
 ## f-slider
 
 - Props (source): `items`, `itemAttr`
-- Behavior: bọc `v-carousel` và `v-carousel-item`
-- Example:
+- Wraps `v-carousel` and `v-carousel-item`
 
 ```json
 {
@@ -119,13 +114,12 @@ Components dùng để hiển thị thông tin, chart, media. File này cũng ch
 
 ## f-echart
 
-→ Xem [`components-echart.md`](components-echart.md) — tài liệu đầy đủ về props, config, global module `FEchartFormatter` và ví dụ.
+→ See [`components-echart.md`](components-echart.md) — props, config, global `FEchartFormatter` module, examples.
 
 ## f-pdfmake
 
 - Props (source): `data`
-- Behavior: render PDF trong iframe, re-render khi `data` thay đổi (deep watch)
-- Example:
+- Renders PDF in an iframe; re-renders when `data` changes (deep watch)
 
 ```json
 {
@@ -140,8 +134,8 @@ Components dùng để hiển thị thông tin, chart, media. File này cũng ch
 
 ---
 
-## Practical Notes
+## Practical notes
 
-1. Hầu hết `f-*` components forward unknown attrs qua `v-bind="$attrs"` — Vuetify attrs vẫn hoạt động nếu child là Vuetify control.
-2. Literal-string rule chỉ áp dụng khi truyền API/path strings trong Action `IN` mapping.
-3. Xem `references/component-table.md` cho `f-table`.
+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`.