@fui-org/fui-cli 1.3.1 → 2.0.0

package/skills/fui-skill/references/component-design.md

@@ -1,63 +1,61 @@
 # FUI Vue Component Design Rules
 
-> File này sở hữu: **quy tắc viết `uc-*.vue`: scope module/project, cấm `name:`/`components:{}`, props/emits/slots, cấm `_injectStyle`, quy tắc scope thủ công cho `<style scoped>`, quy trình kiểm chứng component (`component_preview` + luật push component cấp project trước khi render module), và quy ước `{projectId}/COMPONENTS.md` (tra component project-scope đã có + vòng tích luỹ)**. Bộ class/prop được duyệt xem [controls-styling-vocabulary.md](controls-styling-vocabulary.md).
+> Owns: **`uc-*.vue` rules: module/project scope, no `name:`/`components:{}`, props/emits/slots, no `_injectStyle`, manual `<style scoped>` scoping, verification (`fui component preview`, push project components before module render), `{projectId}/COMPONENTS.md`**. Approved classes/props: [controls-styling-vocabulary.md](controls-styling-vocabulary.md).
 
-Quy tắc bắt buộc khi viết bất kỳ Vue component nào (`uc-*.vue`) trong hệ thống FUI. Áp dụng cho cả component thông thường lẫn dialog component.
+Mandatory for every `uc-*.vue`, dialog components included.
 
 ---
 
-## 1. Hai cấp component: module-scope vs project-scope
+## 1. Two scopes: module vs project
 
-| | Module-scope | Project-scope (global) |
-|---|---|---|
-| **Vị trí file** | `{projectId}/modules/{moduleId}/components/uc-*.vue` | `{projectId}/components/uc-*.vue` |
-| **Registry** | `modules/{moduleId}/components/_components.json` | `{projectId}/components/_components.json` |
-| **Phạm vi** | Chỉ trong module đó | **Tất cả modules trong project** |
-| **Auto-load** | Trong module đã có component | Tự động — **không cần khai báo gì thêm** |
-| **Khi nào dùng** | Component chỉ dùng ở một module | Component dùng lại ở nhiều module |
+|                | Module-scope                                         | Project-scope (global)                    |
+| -------------- | ---------------------------------------------------- | ----------------------------------------- |
+| **File**       | `{projectId}/modules/{moduleId}/components/uc-*.vue` | `{projectId}/components/uc-*.vue`         |
+| **Registry**   | `modules/{moduleId}/components/_components.json`     | `{projectId}/components/_components.json` |
+| **Visible in** | That module only                                     | **All modules in the project**            |
+| **Auto-load**  | In its module                                        | Automatic — **nothing to declare**        |
+| **Use when**   | Used by one module                                   | Reused across modules                     |
 
-> **Project-scope component được FUI tự động load ở cấp global** — bất kỳ module nào trong project đều dùng được `<uc-*>` ngay, không cần tạo lại hay khai báo thêm.
-
-### Quy tắc chọn scope
+### Choosing scope
 
 ```
 Component này sẽ dùng ở nhiều module? → project-scope
 Component chỉ dùng trong một module?   → module-scope
 ```
 
-### Bảng thao tác theo scope
+### Commands per scope
 
-| Thao tác | Module-scope | Project-scope (global) |
-|---|---|---|
-| **Tạo mới** (chưa có trên server) | `component_new(componentName)` — dùng session.moduleId | `component_new(componentName, projectId=<pid>)` — KHÔNG có moduleId |
-| **Cập nhật** (đã có trên server) | `component_update(componentName)` — dùng session.moduleId | `component_update(componentName, projectId=<pid>)` — KHÔNG có moduleId |
-| **Xóa** | `component_delete(componentName)` — dùng session.moduleId | `component_delete(componentName, projectId=<pid>)` — KHÔNG có moduleId |
-| **Đọc source** | `component_get(projectId, moduleId, componentName)` | `component_get(projectId, componentName)` — bỏ moduleId |
-| **Sync danh sách** | `component_list(projectId, moduleId)` | `component_list(projectId)` — bỏ moduleId |
-| **File trong workspace** | `{moduleDir}/components/uc-foo.vue` | `{projectDir}/components/uc-foo.vue` |
+| Operation                  | Module-scope                                        | Project-scope (global)                             |
+| -------------------------- | --------------------------------------------------- | -------------------------------------------------- |
+| **Create** (not on server) | `fui component new <name>` — uses session module    | `fui component new <name> -p <pid>` — NO module    |
+| **Update** (on server)     | `fui component update <name>` — uses session module | `fui component update <name> -p <pid>` — NO module |
+| **Delete**                 | `fui component delete <name>` — uses session module | `fui component delete <name> -p <pid>` — NO module |
+| **Read source**            | `fui component get <name> -p <pid> -m <mid>`        | `fui component get <name> -p <pid>` — omit module  |
+| **Sync list**              | `fui component list -p <pid> -m <mid>`              | `fui component list -p <pid>` — omit module        |
+| **Workspace file**         | `{moduleDir}/components/uc-foo.vue`                 | `{projectDir}/components/uc-foo.vue`               |
 
-**Quy tắc duy nhất:** `moduleId` có → module-scope · `moduleId` vắng, chỉ `projectId` → project-scope
+**Single rule:** module given → module-scope · no module, only project → project-scope. Flags: `fui component --help`.
 
-**Tạo và cập nhật là HAI tool riêng — không có upsert ngầm.** Cả hai đọc file `.vue` **local** (file phải tồn tại sẵn trên đĩa) và tự suy `ComID` từ `_components.json`, không truyền tay:
+**Create ≠ update — no implicit upsert.** Both read the **local** `.vue` (must exist on disk) and derive `ComID` from `_components.json` (never pass it):
 
-- `component_new` — chỉ INSERT. Làm mới `_components.json` **từ server trước** rồi mới kiểm tra tên; trùng tên = **lỗi cứng**. (Cache cũ mà cứ INSERT thì server sinh **hai record cùng tên**, không sửa được từ MCP.) Sau khi tạo tự sync lại để lấy `ComID` thật.
-- `component_update` — chỉ UPDATE. Không tra được `ComID` = **lỗi cứng**, không âm thầm tạo mới: hoặc component chưa từng được tạo (→ `component_new`), hoặc cache local cũ (→ `component_list` rồi thử lại).
+- `fui component new` — INSERT only. Refreshes `_components.json` **from the server first**, then checks the name; duplicate = **hard error** (INSERT on a stale cache creates **two same-name records**, unfixable from fui). Re-syncs after to get the real `ComID`.
+- `fui component update` — UPDATE only. No `ComID` = **hard error**, never creates: never created (→ `fui component new`) or stale cache (→ `fui component list`, retry).
 
-**`component_delete` tự lookup ComID** từ `_components.json` local. Nếu danh sách lệch, chạy `component_list` trước.
+`fui component delete` looks up ComID in local `_components.json`; stale → `fui component list` first.
 
-**`module_publish_html` không bao gồm project-scope component** — nếu có thay đổi component global, phải gọi `component_new`/`component_update` riêng trước hoặc sau.
+**`fui module publish html` excludes project-scope components** — push them separately (`fui component new`/`update`).
 
 ---
 
-## 1a. Tra cứu component project-scope đã có — `{projectId}/COMPONENTS.md`
+## 1a. Existing project components — `{projectId}/COMPONENTS.md`
 
-Trước khi thiết kế một component cấp project mới, **phải kiểm tra `{projectId}/COMPONENTS.md`** (nếu có) — file này liệt kê các `uc-*.vue` cấp project đã tồn tại, kèm tóm tắt mục đích và props chính. Dựng lại component đã có chỉ gây trùng lặp và khó bảo trì.
+Before designing a project-scope component, **check `{projectId}/COMPONENTS.md`** (if present): existing project `uc-*.vue` with purpose and main props. Don't rebuild one that exists.
 
 ```
-{FUI_MCP_WORKDIR}/{projectId}/COMPONENTS.md    ← kiểm tra TRƯỚC khi tạo component project-scope mới
+{workspace}/{projectId}/COMPONENTS.md    ← kiểm tra TRƯỚC khi tạo component project-scope mới
 ```
 
-**Vòng tích luỹ:** sau khi tạo/cập nhật một component cấp project có ý định dùng lại ở nhiều module, nối thêm một mục vào `{projectId}/COMPONENTS.md`. Chưa có file thì tạo mới theo khuôn:
+**Accumulation:** after creating/updating a reusable project component, append an entry; no file → create with:
 
 ```markdown
 # {projectId} — Danh sách component project-scope
@@ -70,24 +68,21 @@ Trước khi thiết kế một component cấp project mới, **phải kiểm t
 **Ghi chú:** điều gì cần biết khi dùng (nếu có)
 ```
 
-> Khuôn này theo đúng `{projectId}/DESIGN.md` (vòng tích luỹ quy tắc thẩm mỹ — xem [design-modes.md](design-modes.md) §2-3). File `COMPONENTS.md` **không bao giờ tự xoá mục** — xoá khi đã dùng `component_delete` bỏ component đó khỏi server.
+> Mirrors `{projectId}/DESIGN.md` ([design-modes.md](design-modes.md) §2-3). **Never auto-remove entries** — remove only after `fui component delete` removed it from the server.
 
 ---
 
-## 2. Đặt tên và cấu trúc file
+## 2. Naming and file layout
 
-- **Prefix bắt buộc**: `uc-` (User Component) — phân biệt với `f-*` (FUI runtime) và `v-*` (Vuetify)
-- **Format**: kebab-case — ví dụ `uc-trangthai-sukien.vue`, `uc-user-profile.vue`
-- **Vị trí**: chỉ đặt trong `components/` ở root module hoặc root project, không tạo subfolder
-- **Registry**: khai báo trong `components/_components.json` (chỉ cần `comName`, không tự đặt `comID`)
+- Prefix `uc-` (User Component; vs `f-*` FUI runtime, `v-*` Vuetify), kebab-case: `uc-trangthai-sukien.vue`, `uc-user-profile.vue`
+- Only in `components/` at module or project root; no subfolders
+- Registry `components/_components.json`: only `comName`, never set `comID`
 
 ---
 
-## 3. Đăng ký component — KHÔNG dùng `components: {}`, KHÔNG dùng `name:`
-
-FUI tự động scan và đăng ký toàn bộ `uc-*.vue` ở cấp **global**. Tuyệt đối không khai báo `components: { ... }` bên trong một component — nó không hoạt động trong môi trường FUI.
+## 3. Registration — NO `components: {}`, NO `name:`
 
-Không khai báo thuộc tính `name:` trong `export default` — FUI tự xử lý tên component từ tên file khi tạo script, khai báo thêm là thừa và có thể gây xung đột:
+FUI auto-registers every `uc-*.vue` **globally**. Never declare `components: { ... }` (doesn't work in FUI) or `name:` (FUI derives it from the filename; may conflict):
 
 ```js
 // ❌ SAI — không cần và có thể gây xung đột
@@ -105,8 +100,8 @@ export default {
 ```js
 // ❌ SAI — không dùng trong FUI
 export default {
-  components: { 'uc-user-card': UcUserCard },
-}
+  components: { "uc-user-card": UcUserCard },
+};
 
 // ✅ ĐÚNG — dùng trực tiếp tag trong template
 // <uc-user-card :data="data" />
@@ -116,9 +111,8 @@ export default {
 
 ## 4. Props
 
-- Khai báo trong `script`: camelCase (`userName`, `itemList`)
-- Dùng trong `template`: kebab-case (`:user-name="userName"`)
-- Default của Array/Object phải dùng `function()`, không dùng arrow function:
+- `script`: camelCase (`userName`, `itemList`); `template`: kebab-case (`:user-name="userName"`)
+- Array/Object defaults use `function()`, not arrow functions:
 
 ```js
 // ❌ SAI
@@ -128,24 +122,23 @@ props: { items: { default: () => [] } }
 props: { items: { default: function() { return [] } } }
 ```
 
-- Ưu tiên tên props trung lập và tái sử dụng được: `items`, `value`, `label`, `loading`, `readonly`, `disabled`, `options`, `config`
-- Không đặt tên props gắn chặt với một màn hình cụ thể nếu component có thể dùng lại
+- Prefer neutral reusable names (`items`, `value`, `label`, `loading`, `readonly`, `disabled`, `options`, `config`), not screen-specific ones
 
 ---
 
 ## 5. Emits
 
-- Luôn emit lên parent thay vì mutate trực tiếp state của parent
-- Các event chuẩn: `input`, `change`, `select`, `submit`, `remove`, `action`
-- Dialog component luôn emit `('input', false)` để đóng — tương thích với `v-model` Vue 2
+- Emit to the parent; never mutate parent state
+- Standard: `input`, `change`, `select`, `submit`, `remove`, `action`
+- Dialog components always close with `('input', false)` — Vue 2 `v-model` compatible
 
 ---
 
-## 6. Template syntax — các ràng buộc bắt buộc
+## 6. Template syntax constraints
 
-### Không dùng backtick trong `<template>`
+### No backticks in `<template>`
 
-Template strings (backtick) không hoạt động đúng trong Vue 2 template. Dùng string concatenation:
+Breaks in Vue 2 templates; concatenate:
 
 ```html
 <!-- ❌ SAI -->
@@ -155,11 +148,11 @@ Template strings (backtick) không hoạt động đúng trong Vue 2 template. D
 :label="'Total (' + items.length + ')'"
 ```
 
-### Không dùng `@` shorthand cho events trong JSON
+### No `@` shorthand in JSON
 
-Trong `module.json` luôn dùng `v-on:click`, không dùng `@click`. Trong `.vue` template thì `@click` vẫn hợp lệ.
+`module.json`: always `v-on:click`, never `@click`. `.vue` templates: `@click` is fine.
 
-### Vue 2 yêu cầu một root element duy nhất
+### Vue 2 needs a single root element
 
 ```html
 <!-- ✅ ĐÚNG -->
@@ -172,13 +165,13 @@ Trong `module.json` luôn dùng `v-on:click`, không dùng `@click`. Trong `.vue
 
 ---
 
-## 7. Style & class — ƯU TIÊN class Vuetify có sẵn, KHÔNG tự chế
+## 7. Style & class — use existing Vuetify classes, DON'T invent
 
-**Quy tắc: dùng class tiện ích Vuetify có sẵn cho MỌI nhu cầu spacing/flex/text/màu/kích thước. Chỉ định nghĩa class mới khi thật đặc biệt** (hiệu ứng/layout Vuetify không có). AI hay lạm dụng class tự chế → lãng phí, phá tính nhất quán, khó bảo trì.
+**Use Vuetify utility classes for ALL spacing/flex/text/color/size. New class only when truly special** (effect/layout Vuetify lacks) — invented classes break consistency.
 
-### ❌ TUYỆT ĐỐI KHÔNG inject CSS bằng JavaScript
+### ❌ NEVER inject CSS via JavaScript
 
-Không tạo `<style>` bằng JS rồi chèn vào `document.head` (kiểu `_injectStyle`) — đây là anti-pattern nặng (vừa lách luật no-`<style>`, vừa tạo hàng chục class tự chế):
+No `<style>` created in JS and appended to `document.head` (`_injectStyle`) — severe anti-pattern (dodges the no-`<style>` rule, spawns invented classes):
 
 ```js
 // ❌ SAI NGHIÊM TRỌNG — không bao giờ làm thế này trong .vue
@@ -191,10 +184,10 @@ methods: {
 }
 ```
 
-`<style scoped>` trong `.vue` được phép dùng cho CSS tùy chỉnh (hiếm khi cần) — nhưng `scoped` **không có tác dụng scoping thật**: FUI chỉ nối text `ComCSS` của mọi component trong module thành MỘT stylesheet chung (`ComponentCSSBuild()`), không compile SFC, không gắn `data-v-xxxx`. Vì vậy **bắt buộc tự scope thủ công**:
+`<style scoped>` is allowed for custom CSS (rarely needed), but **does not scope**: FUI concatenates every module component's `ComCSS` into ONE stylesheet (`ComponentCSSBuild()`) — no SFC compile, no `data-v-xxxx`. **Scope manually**:
 
-1. Thẻ gốc trong `<template>` mang một class định danh duy nhất theo tên component (kebab-case) — ví dụ component `uc-invoice-list` thì thẻ gốc `class="uc-invoice-list"`.
-2. MỌI selector trong `<style scoped>` phải là descendant bắt đầu từ class đó — **không viết selector trần** (`.title`, `.header`...) vì sẽ leak sang mọi component khác cùng module.
+1. Template root gets a class = component name (`uc-invoice-list` → `class="uc-invoice-list"`).
+2. EVERY selector starts from that class — **no bare selectors** (`.title`, `.header`...); they leak into every component in the module.
 
 ```vue
 <template>
@@ -207,58 +200,57 @@ methods: {
 </template>
 
 <style scoped>
-.uc-invoice-list__toolbar { display: flex; align-items: center; justify-content: space-between; }
-.uc-invoice-list__title { font-weight: 600; font-size: 14px; }
-.uc-invoice-list__table { margin-top: 8px; }
+.uc-invoice-list__toolbar {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+}
+.uc-invoice-list__title {
+  font-weight: 600;
+  font-size: 14px;
+}
+.uc-invoice-list__table {
+  margin-top: 8px;
+}
 </style>
 ```
 
 ```vue
 <!-- ❌ SAI — selector trần, đụng với component khác cùng module có class .title/.toolbar -->
 <style scoped>
-.title { font-weight: 600; }
-.toolbar { display: flex; }
+.title {
+  font-weight: 600;
+}
+.toolbar {
+  display: flex;
+}
 </style>
 ```
 
-CSS toàn-module (không gắn riêng component nào) → đặt trong `style.css` (publish qua `module_publish_css`), không phải `header.html`. `header.html` vẫn hợp lệ nhưng không còn là lựa chọn duy nhất.
-
-### Trước khi đặt một class mới → tra bộ từ vựng đã duyệt
+Module-wide CSS → `style.css` (`fui module publish css`); `header.html` still works but isn't the only option.
 
-Bảng đầy đủ class/prop Vuetify được phép dùng (spacing, flex, text, màu, bo góc, elevation,
-breakpoint, kích thước) + thứ tự ưu tiên + điều kiện được định nghĩa class riêng:
-→ [controls-styling-vocabulary.md](controls-styling-vocabulary.md) §3.
+### Before adding a class → check the approved vocabulary
 
-Bộ từ vựng đó áp dụng y nguyên trong `<template>` của `.vue` — **khác biệt duy nhất**: trong `.vue`
-không có `w`/`col` của grid FUI (đó là cú pháp của `module.json`, runtime FUI dịch ra class), nên
-phải viết grid Vuetify trực tiếp.
+Allowed Vuetify classes/props (spacing, flex, text, color, radius, elevation, breakpoint, size), priority, when a custom class is allowed → [controls-styling-vocabulary.md](controls-styling-vocabulary.md) §3. Applies unchanged in `.vue`, **except** no FUI grid `w`/`col` (`module.json` syntax translated by the runtime) — write the Vuetify grid directly.
 
-**Cú pháp grid KHÁC NHAU giữa hai framework** — FUI V2 dùng Vuetify 1.5, FUI V3 dùng Vuetify 3
-(canonical: [controls-patterns.md](controls-patterns.md) §Vuetify version):
+**Grid syntax DIFFERS by framework** — FUI V2 = Vuetify 1.5, FUI V3 = Vuetify 3 (canonical: [controls-patterns.md](controls-patterns.md) §Vuetify version):
 
-| | V2 (Vuetify 1.5) | V3 (Vuetify 3) |
-|---|---|---|
-| Cách chia cột | `v-layout` > `v-flex xs8` | `v-row` > `v-col cols="8"` |
-| `v-flex` | ✅ | ❌ **không tồn tại** — thẻ rơi xuống thành phần tử HTML trơ: không lỗi, không `[Vue warn]`, chỉ là **layout mất hẳn** |
-| `v-layout` | ✅ hàng của grid | ⚠️ **có tồn tại nhưng nghĩa khác hẳn**: là wrapper bố cục ứng dụng (đi với `v-main`, như `fastproject-3.0.js` dùng), KHÔNG phải hàng của grid. Dùng nó thay `v-row` thì được một flex container không có gutter/breakpoint của grid |
-| prop trần `shrink` | ✅ (prop của `v-flex`) | ❌ không có prop đó → rơi thành attribute DOM trơ. Dùng `class="shrink"` |
+|                    | V2 (Vuetify 1.5)          | V3 (Vuetify 3)                                                                                                                                                                                               |
+| ------------------ | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Columns            | `v-layout` > `v-flex xs8` | `v-row` > `v-col cols="8"`                                                                                                                                                                                   |
+| `v-flex`           | ✅                        | ❌ **does not exist** — renders as an inert HTML element: no error, no `[Vue warn]`, just **layout gone**                                                                                                    |
+| `v-layout`         | ✅ grid row               | ⚠️ **exists with a different meaning**: app layout wrapper (with `v-main`, as `fastproject-3.0.js` uses), NOT a grid row. Using it instead of `v-row` gives a flex container without grid gutter/breakpoints |
+| bare prop `shrink` | ✅ (`v-flex` prop)        | ❌ no such prop → inert DOM attribute. Use `class="shrink"`                                                                                                                                                  |
 
-Template chuẩn ở mục 8 ngay dưới viết theo **V3** (`v-row`/`v-col`). Component viết cho project V2 thì
-đổi sang `v-layout`/`v-flex` tương ứng.
+§8 is **V3** (`v-row`/`v-col`); V2 projects use `v-layout`/`v-flex`. Silent breakage both ways: `v-flex` in V3 **shows content with wrong layout**, nothing reports it. Fixing an old component → `fui component preview` on **the project's framework** before pushing.
 
-Đây là lỗi hỏng-âm-thầm theo cả hai chiều: component dùng `v-flex` đưa sang project V3 sẽ **hiện đủ
-nội dung nhưng sai bố cục**, và không tầng nào báo. Sửa component cũ thì kiểm bằng `component_preview`
-ở **đúng framework của project** trước khi push.
-
-CSS tùy chỉnh riêng component (nếu thật sự cần) đặt trong `<style scoped>` của chính `.vue` đó, tự
-scope thủ công theo quy tắc ở mục 7 phía trên — không đặt trong `header.html` trừ khi CSS đó dùng
-chung cho nhiều component/toàn module.
+Component-specific CSS → its own `<style scoped>`, manually scoped — not `header.html` unless shared by several components/the module.
 
 ---
 
-## 8. Dialog chuẩn trong Vue component (`uc-*.vue`) — TEMPLATE CHUẨN HOÁ
+## 8. Standard dialog in `uc-*.vue` — STANDARD TEMPLATE
 
-Dùng `v-dialog` + `v-card` với **quy ước spacing/size cố định** dưới đây cho MỌI dialog form. Chỉ dùng class tiện ích Vuetify — không tự chế class, không `style`.
+EVERY form dialog: `v-dialog` + `v-card` with these **fixed conventions**. Vuetify utility classes only — no invented classes, no `style`.
 
 ```html
 <v-dialog v-model="editDialog" max-width="600">
@@ -274,12 +266,17 @@ Dùng `v-dialog` + `v-card` với **quy ước spacing/size cố định** dư
     <v-card-text class="px-3 py-1">
       <v-row>
         <v-col cols="8">
-          <v-text-field v-model="editItem.RoundName" label="Tên vòng thi"
-                        hide-details outlined dense></v-text-field>
+          <v-text-field v-model="editItem.RoundName" label="Tên vòng thi" hide-details outlined dense></v-text-field>
         </v-col>
         <v-col cols="4">
-          <v-text-field v-model.number="editItem.RoundOrder" label="Thứ tự" type="number"
-                        hide-details outlined dense></v-text-field>
+          <v-text-field
+            v-model.number="editItem.RoundOrder"
+            label="Thứ tự"
+            type="number"
+            hide-details
+            outlined
+            dense
+          ></v-text-field>
         </v-col>
       </v-row>
     </v-card-text>
@@ -294,51 +291,51 @@ Dùng `v-dialog` + `v-card` với **quy ước spacing/size cố định** dư
 </v-dialog>
 ```
 
-### Quy ước bắt buộc (không đổi tuỳ tiện)
+### Mandatory conventions (don't change arbitrarily)
 
-| Phần | Class/prop chuẩn | Ghi chú |
-|---|---|---|
-| `v-dialog` | `max-width="600"` | 600 cho form thường; 400 nhỏ; 800–900 form rộng |
-| `v-card-title` | `d-flex align-center px-3 pt-2 pb-3 subtitle-1 font-weight-bold` | Tiêu đề gọn + nút X (`v-btn icon` → `mdi-close`) bên phải qua `v-spacer` |
-| `v-card-text` | `px-3 py-1` | Padding nội dung nhất quán |
-| Field nhập | `outlined dense hide-details` | Gọn, cùng chiều cao; chia cột bằng `v-row` + `v-col cols="N"` |
-| `v-card-actions` | Là **hàng cuối**; `pa-3` + `v-spacer` trước nhóm nút | Toàn bộ action căn phải |
-| Chiều ngang nút | Không đặt `block`, `width`, class grow hay bọc trong cột giãn | Giữ chiều ngang tự nhiên theo nhãn |
-| Nút chính | Tối đa một nút dùng `color="primary" elevation="0"` + `:loading="saving"` | Có nền để thể hiện ưu tiên; `:loading` khi đang gọi API |
-| Nút phụ | `text`, không `color` nền | Dùng cho action ít quan trọng; giao diện nhã nhặn, tối giản |
+| Part             | Class/prop                                                             | Note                                                                              |
+| ---------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| `v-dialog`       | `max-width="600"`                                                      | 600 normal form; 400 small; 800–900 wide form                                     |
+| `v-card-title`   | `d-flex align-center px-3 pt-2 pb-3 subtitle-1 font-weight-bold`       | Compact title + X button (`v-btn icon` → `mdi-close`) on the right via `v-spacer` |
+| `v-card-text`    | `px-3 py-1`                                                            | Consistent content padding                                                        |
+| Input fields     | `outlined dense hide-details`                                          | Compact, equal height; columns via `v-row` + `v-col cols="N"`                     |
+| `v-card-actions` | **Last row**; `pa-3` + `v-spacer` before buttons                       | All actions right-aligned                                                         |
+| Button width     | No `block`, `width`, grow class or stretched column wrapper            | Natural width from label                                                          |
+| Primary button   | At most one with `color="primary" elevation="0"` + `:loading="saving"` | Filled to show priority; `:loading` during API call                               |
+| Secondary button | `text`, no background `color`                                          | Minor actions; understated                                                        |
 
-- Tiêu đề động theo chế độ: `{{ editItem.ID ? 'Chỉnh sửa' : 'Thêm mới' }}`.
-- Số nhập dùng `v-model.number` + `type="number"`.
-- Đóng dialog: `@click="dialogVar = false"`; sau khi lưu thành công cũng set `false` trong callback.
-- Icon giữ kích thước mặc định; không tự thêm `small`/`:small` cho `v-icon` hoặc nút icon.
+- Mode-dependent title: `{{ editItem.ID ? 'Chỉnh sửa' : 'Thêm mới' }}`.
+- Numbers: `v-model.number` + `type="number"`.
+- Close: `@click="dialogVar = false"`; also set `false` in the callback after a successful save.
+- Keep default icon size; never add `small`/`:small` to `v-icon` or icon buttons.
 
-### Biến thể
+### Variants
 
-- **Toolbar header** (khi cần màu/icon nổi bật): thay `v-card-title` bằng `v-toolbar dense flat` + `v-toolbar-title`.
-- **Fullscreen** (form lớn/nhiều vùng): `<v-dialog v-model="..." fullscreen>` + `v-toolbar` header, nội dung trong `v-container class="grid-list-md"`.
+- **Toolbar header** (color/icon emphasis): replace `v-card-title` with `v-toolbar dense flat` + `v-toolbar-title`.
+- **Fullscreen** (large/multi-area form): `<v-dialog v-model="..." fullscreen>` + `v-toolbar` header, content in `v-container class="grid-list-md"`.
 
 ---
 
-## 9. Thiết kế cho tái sử dụng
+## 9. Design for reuse
 
-- Kiểm tra xem component có thể là: list, card, dialog body, filter panel, summary block, form section không
-- Expose loading/empty/disabled/readonly qua props hoặc slots thay vì hardcode một workflow
-- Giữ API calls, routing, permissions trong `module.json` hoặc parent — component chỉ lo presentation
-- Khi module.json `controls` vượt ~200 dòng: extract UI sang Vue component, giữ module.json chỉ có data/API
+- Shape as list, card, dialog body, filter panel, summary block or form section where possible
+- Expose loading/empty/disabled/readonly via props/slots, don't hardcode a workflow
+- API calls, routing, permissions stay in `module.json` or parent — component = presentation
+- module.json `controls` > ~200 lines → extract UI to a Vue component; module.json keeps data/API
 
 ---
 
-## 10. Không nhúng `f-dialog` vào template component
+## 10. No `f-dialog` inside a component template
 
-`f-dialog` chỉ hoạt động khi khai báo trực tiếp trong `controls` JSON của module. Nếu cần dialog trong một `uc-*.vue`, dùng cấu trúc v-dialog ở mục 7 thay thế.
+`f-dialog` works only directly in the module's `controls` JSON. In `uc-*.vue` use the §8 v-dialog.
 
 ---
 
-## 11. Giới hạn cú pháp trong `<script>` của component
+## 11. `<script>` syntax limits
 
-### Không dùng `async / await / finally`
+### No `async / await / finally`
 
-FUI parser không hỗ trợ các keyword này bên trong file `.vue`. Dùng callback thay thế:
+Unsupported by the FUI `.vue` parser; use callbacks:
 
 ```js
 // ❌ SAI
@@ -352,27 +349,27 @@ mounted() {
 }
 ```
 
-### Không dùng template literals (backtick) trong `<script>`
+### No template literals (backticks) in `<script>`
 
-Backtick chỉ hoạt động trong `script.js` độc lập, không dùng được trong file `.vue`:
+Only work in standalone `script.js`:
 
 ```js
 // ❌ SAI — trong .vue <script>
-var url = `/api/Student/${this.studentID}`
+var url = `/api/Student/${this.studentID}`;
 
 // ✅ ĐÚNG
-var url = '/api/Student/' + this.studentID
+var url = "/api/Student/" + this.studentID;
 ```
 
 ---
 
-## 12. Tận dụng hàm có sẵn trong `defaultfunction.js` — KHÔNG viết lại
+## 12. Reuse `defaultfunction.js` — DON'T rewrite
 
-FUI đã cung cấp sẵn nhiều hàm global. **Trước khi tự viết logic (gọi API, xác nhận, thông báo, format, group, copy...) → kiểm tra [default-function.md](default-function.md) xem đã có chưa.** Chỉ tự viết khi hàm có sẵn không đáp ứng được. Viết lại thứ đã có = lãng phí + không nhất quán.
+**Before writing logic (API call, confirm, notify, format, group, copy...) → check [default-function.md](default-function.md).** Write your own only if nothing fits.
 
-### Gọi API — dùng `ajaxCALL` (KHÔNG `fetch`/`axios`/`$.ajax` thủ công)
+### API calls — `ajaxCALL` (NOT hand-rolled `fetch`/`axios`/`$.ajax`)
 
-`fetch` bị lỗi CORS/credentials sang domain khác. `ajaxCALL` tự xử lý credentials, token (Bearer), và base domain (`v_Set.apiDomain`) — không cần ghép domain.
+`fetch` fails cross-domain (CORS/credentials). `ajaxCALL` handles credentials, Bearer token and base domain (`v_Set.apiDomain`) — don't prepend it.
 
 ```js
 // ❌ SAI
@@ -387,7 +384,7 @@ ajaxCALL('spAPI_RoundList', { ContestID: this.contestID }, function(res) {
 })
 ```
 
-### Xác nhận — dùng `confirm` (KHÔNG `window.confirm`)
+### Confirm — `confirm` (NOT `window.confirm`)
 
 ```js
 confirm({
@@ -397,59 +394,55 @@ confirm({
 });
 ```
 
-### Thông báo — dùng `showMessage` hoặc `Vue.$toast`
+### Notify — `showMessage` or `Vue.$toast`
 
 ```js
-showMessage({ title: 'Đã lưu thành công' });              // hộp thoại
-showMessage({ title: 'Lỗi', message: '...', type: 'red' });
-Vue.$toast.success('Đã lưu', { position: 'top' });         // toast góc màn hình
+showMessage({ title: "Đã lưu thành công" }); // hộp thoại
+showMessage({ title: "Lỗi", message: "...", type: "red" });
+Vue.$toast.success("Đã lưu", { position: "top" }); // toast góc màn hình
 ```
 
-### Các hàm hay dùng khác (đừng viết lại)
+### Other common helpers (don't rewrite)
 
-`groupBy` · `findInArray` · `jsonToExcel` (xuất Excel) · `printPDF` · `copyToClipboard` · `openWindow` · `pushRouter` · `rightTest` (kiểm tra quyền) · `generateID` · `capacityText` · `buildHeader` (tự sinh headers f-table). Chi tiết: [default-function.md](default-function.md).
+`groupBy` · `findInArray` · `jsonToExcel` (Excel export) · `printPDF` · `copyToClipboard` · `openWindow` · `pushRouter` · `rightTest` (permission check) · `generateID` · `capacityText` · `buildHeader` (auto f-table headers). Details: [default-function.md](default-function.md).
 
-> Thư viện toàn cục cũng có sẵn — dùng thay vì tự cài: `_` (Lodash: `_.groupBy`, `_.sumBy`, `_.cloneDeep`...), `moment` (ngày giờ), `numeral` (format số). Không thêm CDN cho các thư viện này.
+> Globals — never add a CDN for them: `_` (Lodash: `_.groupBy`, `_.sumBy`, `_.cloneDeep`...), `moment` (dates), `numeral` (numbers).
 
 ---
 
-## 13. Kiểm chứng component — `component_preview` TRƯỚC khi ráp vào module
+## 13. Verify with `fui component preview` BEFORE assembling into the module
 
-Một `uc-*.vue` là đơn vị đầy đủ (template + script + style) nhưng nếu chỉ nhìn thấy nó sau khi đã ráp vào module thì lỗi của component và lỗi lắp ráp trộn lẫn — mất thời gian khoanh vùng. `component_preview` render **đúng một component** trên một trang riêng, bằng file `.vue` **local** (chưa cần push), với dữ liệu mẫu bạn truyền thẳng trong tham số.
+Seen only after assembly, component bugs and assembly bugs mix. `fui component preview` renders **one component** on its own page from the **local** `.vue` (no push needed) with sample data passed directly.
 
 ```
-component_preview({
-  componentName: "uc-invoice-list",
-  projectId: "...",              // chỉ projectId → project-scope
-  // moduleId: "..."             // có moduleId → module-scope (suy luận y hệt component_new/component_update)
-  cases: [
-    { name: "danh sách rỗng",  props: { items: [] } },
-    { name: "có dữ liệu",      props: { items: [ {...}, {...} ], title: "Hoá đơn" } },
-    { name: "click chọn dòng", props: { items: [...] },
-      scenario: [ { click: "Xem" }, { assert: "vueData.selected != null" } ] }
-  ],
-  devices: ["desktop", "mobile"]   // mặc định
-})
+fui component preview uc-invoice-list -p <pid> --cases '[
+  { "name": "danh sách rỗng",  "props": { "items": [] } },
+  { "name": "có dữ liệu",      "props": { "items": [ {...}, {...} ], "title": "Hoá đơn" } },
+  { "name": "click chọn dòng", "props": { "items": [...] },
+    "scenario": [ { "click": "Xem" }, { "assert": "vueData.selected != null" } ] }
+]'
+# -p only → project-scope; add -m <mid> → module-scope (same inference as fui component new/update)
+# devices default: desktop + mobile
 ```
 
-- **Props**: mảng/object cứ truyền **giá trị thật** — tool tự đẩy vào `data[]` và bind `:prop`. Chuỗi thành attr tĩnh; key đã bắt đầu bằng `:`/`v-` giữ nguyên văn (dùng `v-on:`/`v-slot:`, **không** `@`/`#`).
-- **`cases × devices` ≤ 8**. Mỗi lần render là một phiên browser thật.
-- `slot` (nội dung `innerHTML`), `vueData`, `apiMocks`, `user` (test permission gate), `viewport` (ép chiều cao thấp để lộ component tự đo chiều cao) đều truyền được.
-- `scenario` dùng **đúng grammar renderUI trên DOM thật**: `set`/`click`/`call`/`exe`/`assert`, chọn dòng bằng `nth` (không có `item`/`index`).
-- **`style.css` của module KHÔNG được nạp** — đó chính là ý nghĩa "không gian riêng": component phải tự đứng được bằng `<style>` của chính nó + theme project.
-- Trả về: ảnh chụp (tối đa 4 inline, còn lại ghi đường dẫn) + JS error + `[Vue warn]` + DOM audit. **Đọc ảnh rồi tự sửa** trước khi push.
+- **Props**: arrays/objects as **real values** (pushed into `data[]`, bound `:prop`). Strings → static attrs; keys starting `:`/`v-` kept verbatim (use `v-on:`/`v-slot:`, **not** `@`/`#`).
+- **`cases × devices` ≤ 8** (each render = real browser session).
+- Also accepted: `slot` (`innerHTML` content), `vueData`, mocks, `user` (test permission gates), `viewport` (force low height to expose self-measuring components). Flags: `fui component preview --help`.
+- `scenario` uses **the exact `--render` grammar on the real DOM**: `set`/`click`/`call`/`exe`/`assert`; pick rows with `nth` (no `item`/`index`).
+- **Module `style.css` NOT loaded** — component must stand on its own `<style>` + project theme.
+- Returns: screenshots (max 4 inline, rest as paths) + JS errors + `[Vue warn]` + DOM audit. **Read the images and fix** before pushing.
 
-### Component cấp project: BẮT BUỘC push trước khi render module dùng nó
+### Project components: MUST push before rendering a module that uses them
 
-`module_simulate({ renderUI: true })` dựng tầng project bằng bundle **tải từ server**. Bản local chưa push sẽ **không xuất hiện** — ảnh render là bản cũ trên server, tức ảnh nói dối. Vì vậy renderUI **chặn cứng** (không có cờ bỏ qua) khi component cấp project ở local lệch với bundle server.
+`fui module simulate --render` builds the project layer from the **server** bundle; unpushed local edits **don't appear** (screenshot lies). So `--render` **hard-blocks** (no override) when a local project component differs from the server bundle.
 
 ```
 sửa uc-*.vue cấp project
-  → component_preview   (kiểm chứng bản local, chưa push)
-  → component_new       (lần đầu) hoặc component_update (các lần sau) — push lên server
-  → module_simulate({ renderUI: true })   ← chỉ chạy được sau khi đã push
+  → fui component preview   (kiểm chứng bản local, chưa push)
+  → fui component new       (lần đầu) hoặc fui component update (các lần sau) — push lên server
+  → fui module simulate --render   ← chỉ chạy được sau khi đã push
 ```
 
-Nếu bị chặn mà **bản trên server mới hơn** (ai đó vừa sửa trên web IDE): chạy `project_sync` để lấy về, **đừng push đè** — sẽ mất bài của người khác.
+Blocked and **server is newer** (edited in web IDE) → `fui project sync`; **don't push over it** (erases their work).
 
-Component **cấp module** không bị luật này: renderUI dựng tầng module từ file local nên sửa tới đâu render thấy tới đó.
+**Module-level** components are exempt: the module layer renders from local files.