@fui-org/fui-cli 1.3.2 → 2.0.0

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

@@ -1,77 +1,78 @@
 # FUI Component Quick Reference
 
-> File này sở hữu: **danh mục component FUI, bảng component cần import JS/CSS, quy trình thêm/bỏ import**. Chi tiết từng component xem file reference tương ứng ở cột phải.
+> Owns: **FUI component catalog, components needing JS/CSS imports, add/remove import workflow**. Per-component details: file in the right column.
 
-Tra cứu nhanh toàn bộ component có sẵn trong FUI runtime. Ưu tiên dùng `f-*` trước — chỉ dùng `v-*` khi không có FUI equivalent.
+Prefer `f-*`; use `v-*` only when no FUI equivalent exists.
 
-| Component | Dùng khi nào | Reference |
-|---|---|---|
-| `f-table` | **Hiển thị dữ liệu dạng datatable** — cả CRUD qua dialog form lẫn chỉ xem (readonly = không khai `:update-api`); auto-build headers khi không truyền `:headers`; hàng tổng qua `sum-format` | [component-table.md](component-table.md) |
-| `f-dialog` | Modal dialog với form, watch, button | [components-dialog.md](components-dialog.md) |
-| `f-window` | Dialog mở URL trong iframe | [components-dialog.md](components-dialog.md) |
-| `f-button` | Nút bấm có action, hotkey, form validation | [components-input.md](components-input.md) |
-| `f-date` | Input ngày có date picker + typed mask | [components-input.md](components-input.md) |
-| `f-time` | Input giờ có time picker + typed mask | [components-input.md](components-input.md) |
-| `f-time-counter` | Đếm ngược / đồng hồ | [components-input.md](components-input.md) |
-| `f-search` | Autocomplete tìm kiếm qua API | [components-input.md](components-input.md) |
-| `f-menu` | Dropdown button menu có icon/action/link | [components-input.md](components-input.md) |
-| `f-radiobox` | Radio group từ array items | [components-input.md](components-input.md) |
-| `f-file-upload` | Upload file (Plupload, progress dialog) | [components-input.md](components-input.md) |
-| `f-image-update` | Upload + crop ảnh | [components-input.md](components-input.md) |
-| `f-excel-reader` | Đọc file Excel/CSV → JSON (chọn sheet, bỏ N dòng đầu, tự đặt tên cột) | [components-input.md](components-input.md) |
-| `f-qrcode` | Render mã QR | [components-input.md](components-input.md) |
-| `f-qrcode-reader` | Đọc QR bằng camera | [components-input.md](components-input.md) |
-| `f-editor` | Rich text editor (CKEditor 5) | [components-dialog.md](components-dialog.md) |
-| `f-editor-dialog` | Rich text editor trong modal | [components-dialog.md](components-dialog.md) |
-| `f-echart` | **Biểu đồ** — ECharts V5: bar, line, pie, scatter, gauge, radar, heatmap, sankey, tree, map, graph... | [components-echart.md](components-echart.md) · [echart-templates.md](echart-templates.md) |
-| `f-sheet` | **Nhập liệu trực tiếp trên bảng kiểu Excel** — sửa ô tại chỗ, dán từ Excel, không qua dialog (dựa trên AG Grid) — **cần import** | [fsheet.md](fsheet.md) |
-| `f-pdfmake` | Render PDF trong iframe | [components-display.md](components-display.md) · [pdfmake.md](pdfmake.md) |
-| `f-label` | Chip/badge hiển thị tag, trạng thái | [components-display.md](components-display.md) |
-| `f-box` | Hiển thị/chỉnh sửa key-value rows | [components-display.md](components-display.md) |
-| `f-header` | Tiêu đề lớn (display-1, primary color) | [components-display.md](components-display.md) |
-| `f-title` | Tiêu đề nhỏ (title, primary color) | [components-display.md](components-display.md) |
-| `f-slider` | Carousel ảnh | [components-display.md](components-display.md) |
-| `fp-profile` | Khối thông tin/hồ sơ user | [components-display.md](components-display.md) |
+| Component         | Use for                                                                                                                                                         | Reference                                                                                 |
+| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| `f-table`         | **Any datatable** — CRUD via dialog form or view-only (readonly = omit `:update-api`); auto-builds headers when `:headers` omitted; totals row via `sum-format` | [component-table.md](component-table.md)                                                  |
+| `f-dialog`        | Modal with form, watch, buttons                                                                                                                                 | [components-dialog.md](components-dialog.md)                                              |
+| `f-window`        | Dialog opening a URL in an iframe                                                                                                                               | [components-dialog.md](components-dialog.md)                                              |
+| `f-button`        | Button with action, hotkey, form validation                                                                                                                     | [components-input.md](components-input.md)                                                |
+| `f-date`          | Date input with picker + typed mask                                                                                                                             | [components-input.md](components-input.md)                                                |
+| `f-time`          | Time input with picker + typed mask                                                                                                                             | [components-input.md](components-input.md)                                                |
+| `f-time-counter`  | Countdown / clock                                                                                                                                               | [components-input.md](components-input.md)                                                |
+| `f-search`        | API-backed autocomplete                                                                                                                                         | [components-input.md](components-input.md)                                                |
+| `f-menu`          | Dropdown button menu with icon/action/link                                                                                                                      | [components-input.md](components-input.md)                                                |
+| `f-radiobox`      | Radio group from items array                                                                                                                                    | [components-input.md](components-input.md)                                                |
+| `f-file-upload`   | File upload (Plupload, progress dialog)                                                                                                                         | [components-input.md](components-input.md)                                                |
+| `f-image-update`  | Image upload + crop                                                                                                                                             | [components-input.md](components-input.md)                                                |
+| `f-excel-reader`  | Excel/CSV → JSON (pick sheet, skip first N rows, name columns)                                                                                                  | [components-input.md](components-input.md)                                                |
+| `f-qrcode`        | Render QR code                                                                                                                                                  | [components-input.md](components-input.md)                                                |
+| `f-qrcode-reader` | Read QR via camera                                                                                                                                              | [components-input.md](components-input.md)                                                |
+| `f-editor`        | Rich text editor (CKEditor 5)                                                                                                                                   | [components-dialog.md](components-dialog.md)                                              |
+| `f-editor-dialog` | Rich text editor in a modal                                                                                                                                     | [components-dialog.md](components-dialog.md)                                              |
+| `f-echart`        | **Charts** — ECharts V5: bar, line, pie, scatter, gauge, radar, heatmap, sankey, tree, map, graph...                                                            | [components-echart.md](components-echart.md) · [echart-templates.md](echart-templates.md) |
+| `f-sheet`         | **Excel-like in-grid editing** — edit cells in place, paste from Excel, no dialog (AG Grid) — **needs import**                                                  | [fsheet.md](fsheet.md)                                                                    |
+| `f-pdfmake`       | Render PDF in iframe                                                                                                                                            | [components-display.md](components-display.md) · [pdfmake.md](pdfmake.md)                 |
+| `f-label`         | Chip/badge for tags, status                                                                                                                                     | [components-display.md](components-display.md)                                            |
+| `f-box`           | Display/edit key-value rows                                                                                                                                     | [components-display.md](components-display.md)                                            |
+| `f-header`        | Large heading (display-1, primary color)                                                                                                                        | [components-display.md](components-display.md)                                            |
+| `f-title`         | Small heading (title, primary color)                                                                                                                            | [components-display.md](components-display.md)                                            |
+| `f-slider`        | Image carousel                                                                                                                                                  | [components-display.md](components-display.md)                                            |
+| `fp-profile`      | User info/profile block                                                                                                                                         | [components-display.md](components-display.md)                                            |
 
-### Component trong ô bảng (`t-*`) — dùng trong `headers` của f-table
+### Table-cell components (`t-*`) — used in f-table `headers`
 
-`t-html` · `t-label` · `t-num` · `t-time` · `t-boolean` · `t-check` (toggle) · `t-text` · `t-select` · `t-combobox` · `t-menu` (context menu) · `t-link` · `t-button` — chi tiết & ví dụ: [ui-table-cell-patterns.md](ui-table-cell-patterns.md).
+`t-html` · `t-label` · `t-num` · `t-time` · `t-boolean` · `t-check` (toggle) · `t-text` · `t-select` · `t-combobox` · `t-menu` (context menu) · `t-link` · `t-button` — details: [ui-table-cell-patterns.md](ui-table-cell-patterns.md).
 
-> `header-bar` và `f-window` là component nội bộ do runtime tự dựng (menu header, cửa sổ `openWindow`) — không đặt trực tiếp trong `controls`.
+> `header-bar` and `f-window` are internal, runtime-built (header menu, `openWindow` window) — never place them directly in `controls`.
 
-## Components cần import JS/CSS
+## Components needing JS/CSS imports
 
-Một số component yêu cầu import thêm thư viện — **phải gọi `file_import_list` để kiểm tra và thêm/xóa import tương ứng khi thêm hoặc bỏ component**.
+**When adding or removing one of these, run `fui import list` and add/remove the matching imports.**
 
-| Component | Import bắt buộc |
-|---|---|
-| `f-pdfmake` | `/include/pdfmake/pdfmake.min.js` · `/include/pdfmake/print.min.js` · `/include/pdfmake/vfs_fonts.js` |
-| `f-file-upload` | `/include/plupload-2.3.7/plupload.full.min.js` |
-| `f-image-update` | `/include/vue-advanced-cropper/index.umd.js` · `/include/vue-advanced-cropper/style.css` |
-| `f-qrcode` | `/include/qrcode/qrcode.min.js` |
-| `f-qrcode-reader` | `/include/qrcode/qrcode-reader.min.js` |
-| `f-echart` | `/include/chart/echarts.min.js` · `/include/chart/fechart.js` (**theo thứ tự này**) — nền tảng Apache ECharts |
-| `f-sheet` | `/include/ag-grid/ag-grid-community.min.js` · `/include/ag-grid/fsheet.js` (**theo thứ tự này**) — nền tảng AG Grid |
-| `f-editor` | `/include/ckeditor5/build/ckeditor.js` |
-| `f-editor-dialog` | `/include/ckeditor5/build/ckeditor.js` |
+| Component         | Required imports                                                                                         |
+| ----------------- | -------------------------------------------------------------------------------------------------------- |
+| `f-pdfmake`       | `/include/pdfmake/pdfmake.min.js` · `/include/pdfmake/print.min.js` · `/include/pdfmake/vfs_fonts.js`    |
+| `f-file-upload`   | `/include/plupload-2.3.7/plupload.full.min.js`                                                           |
+| `f-image-update`  | `/include/vue-advanced-cropper/index.umd.js` · `/include/vue-advanced-cropper/style.css`                 |
+| `f-qrcode`        | `/include/qrcode/qrcode.min.js`                                                                          |
+| `f-qrcode-reader` | `/include/qrcode/qrcode-reader.min.js`                                                                   |
+| `f-echart`        | `/include/chart/echarts.min.js` · `/include/chart/fechart.js` (**in this order**) — Apache ECharts       |
+| `f-sheet`         | `/include/ag-grid/ag-grid-community.min.js` · `/include/ag-grid/fsheet.js` (**in this order**) — AG Grid |
+| `f-editor`        | `/include/ckeditor5/build/ckeditor.js`                                                                   |
+| `f-editor-dialog` | `/include/ckeditor5/build/ckeditor.js`                                                                   |
 
-> **Bundled sẵn, KHÔNG cần import thêm:** `v-*` (Vuetify) · `f-table` · `f-dialog` · `f-button` ·
+> **Bundled, NO import needed:** `v-*` (Vuetify) · `f-table` · `f-dialog` · `f-button` ·
 > `f-date` · `f-time` · `f-search` · `f-menu` · `f-radiobox` · `f-box` · `f-label` · `f-header` ·
-> `f-title` · `f-slider` · `f-excel-reader` — và mọi component không có tên trong bảng trên.
+> `f-title` · `f-slider` · `f-excel-reader` — and any component not in the table above.
 
-**Quy trình khi thêm component có import:**
-1. `file_import_list` (projectId + moduleId) — kiểm tra import hiện có
-2. Nếu chưa có → `file_import_new` để thêm từng file
-3. Nếu bỏ component → kiểm tra import đó còn dùng ở chỗ nào khác không; nếu không → `file_import_delete`
+**Workflow when adding a component with imports** (see `fui import --help`):
+
+1. `fui import list` (project + module) — check existing imports
+2. Missing → `fui import new` for each file
+3. Removing a component → check whether the import is still used elsewhere; if not → `fui import delete`
 
 ---
 
-## Quy tắc chọn nhanh
+## Quick selection rules
 
-- `f-button` thay `v-btn` khi cần action FUI (CALL, hotkey, form validation)
-- `f-date` / `f-time` thay `v-text-field` + manual date parsing
-- `f-search` thay `v-autocomplete` khi cần search qua API
-- `f-menu` thay `v-menu + v-btn` khi cần dropdown actions
-- `f-table` thay `v-data-table` cho MỌI bảng — CRUD lẫn chỉ xem (readonly = không khai `:update-api`)
-- `f-echart` cho mọi loại biểu đồ (bar, line, pie, gauge, scatter, radar, sankey, tree, map...)
-- Dialog: `ctrl-update` của `f-table` cho CRUD inline; dialog riêng → dựng `v-dialog` thủ công theo anatomy chuẩn (`design_read("fui")` §4 + `ui-dialog-patterns.md`); `f-dialog` chỉ cho form rất nhỏ
+- `f-button` over `v-btn` when you need FUI actions (CALL, hotkey, form validation)
+- `f-date` / `f-time` over `v-text-field` + manual date parsing
+- `f-search` over `v-autocomplete` for API search
+- `f-menu` over `v-menu + v-btn` for dropdown actions
+- `f-table` over `v-data-table` for EVERY table — CRUD and view-only (readonly = omit `:update-api`)
+- `f-echart` for every chart type (bar, line, pie, gauge, scatter, radar, sankey, tree, map...)
+- Dialogs: `f-table` `ctrl-update` for inline CRUD; standalone dialog → hand-build `v-dialog` per the standard anatomy (`fui design read fui` §4 + `ui-dialog-patterns.md`); `f-dialog` only for very small forms

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

@@ -1,111 +1,106 @@
 # FUI Table Components (Source-Based)
 
-> File này sở hữu: **`f-table` chuyên sâu: mọi props, auto-header, `sum-format`, readonly table**. Điều khiển trong ô (`t-*`) xem [ui-table-cell-patterns.md](ui-table-cell-patterns.md).
+> Owns: **`f-table` in depth: all props, auto-header, `sum-format`, Excel export (`excel`), readonly table**. In-cell controls (`t-*`): [ui-table-cell-patterns.md](ui-table-cell-patterns.md).
 
-This file is derived from `scripts/componentTable.js` (V2) and `scripts/componentTable-3.0.js` (V3).
-Focus: `f-table` and `t-*` renderers.
+Source: `scripts/componentTable.js` (V2), `scripts/componentTable-3.0.js` (V3).
 
-> **Xác định phiên bản trước khi viết headers** — V2 và V3 dùng tên field khác nhau, sai tên thì bảng không render. Xem mục "V2 vs V3 — Sự khác biệt quan trọng" cuối file.
+> **Check the version before writing headers** — V2/V3 field names differ; wrong names = no render. See "V2 vs V3" below.
 
-> `f-table` đảm nhận cả hai vai trò: bảng CRUD và bảng chỉ xem (readonly). Bảng chỉ xem = `f-table` không khai báo `:update-api` (hoặc thêm `:disabled-update true`); có thể bỏ luôn `:headers` để bảng tự dựng header từ dữ liệu (xem Auto Headers bên dưới).
+> `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 for table columns.
-- `v-data-table`: Vuetify internal implementation, but CRUD and table action flow comes from FUI wrappers.
+`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`
+`value`, `headers`, `updateForm`, `updateFormAttr`, `updateApi`, `items`, `label`, `excel`, `showSearch`, `sumFormat`, `disabledHover`, `returnObject`, `itemKey`, `itemsPerPage`, `disabledUpdate`, `hideDefaultFooter`, `template`, `headercomponent`, `height`, `fixedHeader`, `fixedCols`
 
 ### Real Behavior
 
-1. If a header item has `el`, table creates custom slot renderer automatically.
-2. If `updateApi.new` or `updateApi['new-action']` exists, add button appears.
+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. Editing dialog is `f-dialog` with `updateForm`.
-5. Selection result emit:
-- if `returnObject=false`: emit array of `itemKey`
-- if `returnObject=true`: emit selected row objects
-6. Emits row events from slots: `click:row`, `mouseover:row`, `mouseleave:row`.
-7. **Auto headers**: nếu KHÔNG truyền `:headers`, table tự build header từ `items` (xem mục Auto Headers).
-8. **Sum row / sum line**: prop `sum-format` nhận string HOẶC object — hai cách render khác nhau (xem mục sum-format).
-
-### Cố định cột bên trái (`fixed-cols`)
-
-Khai `fixed-cols="N"` để giữ N cột đầu tiên khi cuộn ngang. Tính năng có ở cả FUI V2 và V3; bỏ prop, đặt `0`, hoặc truyền giá trị không hợp lệ thì bảng hoạt động như cũ.
-
-```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" }
-    ]
-  }
-}
-```
-
-- Nên khai `width` cho từng cột được cố định; nếu bỏ trống, `f-table` dùng `150px`.
-- `width` dạng số được hiểu là pixel; chuỗi CSS như `"120px"` vẫn được giữ nguyên.
-- `fixed-cols` đếm theo thứ tự cột render thực tế. Nếu bật cột chọn dòng/group của Vuetify thì các cột hệ thống đó cũng nằm trong phép đếm.
-- CSS được scope theo từng instance `f-table`, nên nhiều bảng có số cột cố định khác nhau có thể cùng xuất hiện trên một trang.
-
-### Auto Headers (khi không truyền `:headers`)
-
-Khi bỏ hẳn prop `:headers`, `f-table` tự build header từ row đầu tiên của `items` (qua `buildHeader`):
-
-- Mỗi key của row → một cột `{ text: key, value: key, divider: true }`; key có giá trị số → tự gắn `el: "t-num"` (format số bên phải).
-- Nếu có `:update-api` với `edit`/`delete` và không `disabled-update` → tự thêm cột `ctrl-update` cuối bảng.
-- Headers được rebuild mỗi khi `items` đổi shape (watch trên `items`) — an toàn khi data load async.
-
-**Khi nào dùng:** bảng hiển thị nhanh, cột đúng bằng field trả về từ API (SP đã alias tên cột đẹp bằng tiếng Việt). **Khi nào KHÔNG dùng (phải khai `:headers` tường minh):** cần label khác tên field, cần ẩn bớt cột, cần `t-*` renderer tùy biến (t-time, t-check, t-link...), cần width/align cụ thể, hoặc data có field kỹ thuật (ID nội bộ, flag) không nên hiển thị.
+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).
+9. **Excel button**: `excel` = `true` exports the raw data, `"UI"` exports exactly what the table shows (see Excel export).
+
+### 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": { "label": "Kết quả", ":items": "dsKetQua", "show-search": true } }
+{
+  "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" }
+    ]
+  }
+}
 ```
 
-### sum-format — Tổng cột (2 dạng)
+- 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.
 
-Prop `sum-format` có 2 dạng, render hoàn toàn khác nhau:
+### Auto Headers (no `:headers`)
 
-**Dạng 1 — string template → MỘT dòng text tổng dưới bảng** (trong `v-card-actions`, KHÔNG nằm trong `v-data-table`, không thẳng cột):
+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]]` được thay bằng `_.sumBy(items, 'FieldName')` format cố định `'0,0'` (numeral).
-- Kết quả là 1 dòng text duy nhất, căn phải, phía dưới bảng (có `v-divider` ngăn cách).
-- Dùng khi: chỉ cần 1 dòng tóm tắt tổng, hoặc tổng của nhiều cột gộp chung 1 câu.
-- Là string tĩnh → khai báo attr KHÔNG có `:` prefix.
+- `[[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.
 
-**Dạng 2 — object → HÀNG TỔNG thật sự trong bảng** (slot `body.append` của `v-data-table`, thẳng theo từng cột):
+**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 = `value` của cột trong headers; value = numeral format string riêng cho cột đó (`"0,0"`, `"0,0.0"`, `"0.0%"`, ...).
-- Render một `<tr>` cuối thân bảng: ô của cột có key trong object hiển thị `_.sumBy(items, key)` theo format tương ứng; các cột khác để trống. Tất cả ô căn phải, `font-weight-medium`.
-- Hàng tổng nằm TRONG bảng nên thẳng hàng với cột, cuộn cùng thân bảng.
-- Là object → khai báo attr CÓ `:` prefix.
+- 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.
 
-**Chọn dạng nào:** user cần "hàng tổng dưới mỗi cột / dòng tổng trong bảng / tổng thẳng cột" → dạng object. User cần "dòng chữ tổng kết chung" → dạng string. **KHÔNG tự dựng hàng tổng thủ công** (không push row "Tổng" vào items, không tự viết template body.append) — dùng `sum-format`.
+**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`.
 
-Ví dụ đầy đủ dạng object:
+Full object example:
 
 ```json
 {
-  "el": "f-table", "w": "12",
+  "el": "f-table",
+  "w": "12",
   "attr": {
     "label": "Thống kê tuyển sinh",
     ":items": "dsThongKe",
@@ -119,15 +114,38 @@ Ví dụ đầy đủ dạng object:
 }
 ```
 
+### Excel export — prop `excel` (2 modes)
+
+Excel button on the table toolbar, in both V2 and V3. **V2**: no `excel` → no button. **V3**: the prop defaults to `true`, so the button always shows; hide it with `":excel": false`.
+
+| Value                            | Rows                                                                                                       | Columns & headers                                                                                             | Cell values                           |
+| -------------------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
+| `true` _(default, old behavior)_ | **All** `items`, original order — ignores search and sorting                                               | Every field of the **first row**, header = raw field name (`HoTen`), including IDs/technical fields not shown | Raw, dates as ISO strings             |
+| `"UI"`                           | Only rows **matching the search box**, in the **current sort order** (including `group-by`), **all pages** | Only columns declared in `headers`, same order, header = `title`/`text` (HTML stripped)                       | **Raw, unformatted data** — as `true` |
+
+```json
+{ "el": "f-table", "w": 12, "attr": { "label": "Danh sách", ":items": "dsHang", "excel": "UI", ":headers": [ ... ] } }
+```
+
+- `"UI"` is a static string → **no** `:` prefix. Case-insensitive (`"ui"` works). Any other value (`true`, `"true"`, …) is the raw mode.
+- **In short:** `"UI"` takes **rows and columns as displayed**, while **cell values stay raw**. User wants "export what I see / filtered / sorted" → `"UI"`. Need every field dumped (IDs, hidden fields) → `true`.
+
+**`"UI"` details:**
+
+- **Filtering** reuses the table's own `customSearch`, so the result matches the rows on screen. **Sorting** follows the current `v-data-table` sort state (caught via `update:options`). If the user has not clicked a column, the `sort-by`/`sort-desc` (V2) or `sort-by` (V3) from attr apply. Strings compare with `Intl.Collator`, so accented Vietnamese sorts correctly.
+- **Pagination does not matter**: the file always holds every page of the filtered set. Collapsed groups (`group-by`) are exported too.
+- **Dropped columns**: `ctrl-update`, system columns (`data-table-select`/`-group`/`-expand`), headers without `key`/`value`. Group headers (`children`, V3) are flattened to `Parent / Child`.
+- **Column field from `v-model`**: a header with `attr["v-model"]: "item.X"` exports field `X`, even when the column `key` is another name. Filtering and sorting still use `key`/`value`, as `v-data-table` does.
+- **Cell value = raw data, NOT formatted**: numbers export as plain numbers (no numFmt, zeros not hidden even with `t-num` `hidezero`), dates as the raw API string (`2026-08-15T00:00:00`, not dd/mm/yyyy), `t-html` as the raw HTML string, `t-select`/`t-check` as the raw code/value, not the label. `format` of `t-num`/`t-time` is **not** applied to the file.
+- **No total row**: `sum-format` only displays on the table; the file has no total line.
+- Need a pre-formatted file (numFmt, real dates, a `SUM` total row) → call `jsonToExcel` with `columns` yourself; see [default-function.md](default-function.md).
+- Only the file presentation is adjusted: header row bold and frozen. Column width comes from the header's px `width` (÷7), else estimated from content. File/sheet name = `label` with HTML stripped (sheet cut to 31 characters), `tableFP` when there is no label.
+- No matching rows → "Không có dòng nào đang hiển thị để xuất Excel", no empty file.
+- **Selected** rows (show-select) do not matter: `"UI"` exports every displayed row, not only the selected ones.
+
 ### updateApi Keys Used By Source
 
-- `new`
-- `edit`
-- `delete`
-- `default-item`
-- `new-action`
-- `edit-action`
-- `data-out`
+`new`, `edit`, `delete`, `default-item`, `new-action`, `edit-action`, `data-out`
 
 ### Minimal CRUD Example
 
@@ -177,7 +195,7 @@ Ví dụ đầy đủ dạng object:
 
 ## Readonly Table
 
-Bảng chỉ xem = `f-table` không có `:update-api` (không hiện nút thêm/sửa/xóa) — bỏ `:headers` nếu muốn auto-build:
+`f-table` without `:update-api` (no add/edit/delete buttons); omit `:headers` to auto-build:
 
 ```json
 {
@@ -196,51 +214,35 @@ Bảng chỉ xem = `f-table` không có `:update-api` (không hiện nút thêm/
 
 ## t-* Cell Renderers
 
-Use in `headers` by setting `el`.
-
-Example header:
+Set `el` in `headers`:
 
 ```json
 { "text": "Ngay tao", "value": "CreatedAt", "el": "t-time", "attr": { "format": "DD/MM/YYYY HH:mm" } }
 ```
 
-### Supported `t-*` components
-
-- `t-html`
-- `t-label`
-- `t-num`
-- `t-time`
-- `t-boolean`
-- `t-check`
-- `t-text`
-- `t-select`
-- `t-combobox`
-- `t-menu`
-- `t-link`
-- `t-button`
+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. For dialog opening in row actions, use `target: "dialog"` plus `wid`, `url`, `title`, `onclose`.
-3. Apply literal-string rule only in Action `IN` mapping.  
-   Static component props without `:` are plain strings by default.
+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 — Sự khác biệt quan trọng (nguồn: `componentTable.js` vs `componentTable-3.0.js`)
+## V2 vs V3 (source: `componentTable.js` vs `componentTable-3.0.js`)
 
-Phiên bản framework được xác định từ `_projectInfo.json` hoặc `_moduleInfo.json` — tra trước khi viết headers.
+Framework version comes from `_projectInfo.json` or `_moduleInfo.json` — check before writing headers.
 
 ### Header field names
 
-**Đây là điểm dễ nhầm nhất.** Hai trường `text`/`value` của V2 đổi tên thành `title`/`key` ở V3:
+**Most common mistake.** V2 `text`/`value` are renamed `title`/`key` in V3:
 
-| Trường | V2 (`componentTable.js`) | V3 (`componentTable-3.0.js`) |
-|---|---|---|
-| Nhãn cột | `"text": "Tên cột"` | `"title": "Tên cột"` |
-| Field data | `"value": "TenField"` | `"key": "TenField"` |
-| Cột ctrl | `"value": "ctrl-update"` | `"key": "ctrl-update"` |
+| 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 ✅
@@ -252,25 +254,34 @@ Phiên bản framework được xác định từ `_projectInfo.json` hoặc `_m
 { "title": "Tác vụ", "key": "ctrl-update", "align": "center" }
 ```
 
-> Dùng `text`/`value` trên project V3 → cột render nhưng **tiêu đề biến mất và sort không hoạt động** (Vuetify 3 đọc `title`/`key`, bỏ qua `text`/`value`). Không có lỗi JS nào báo — chỉ nhìn thấy qua ảnh render.
+> `text`/`value` on V3 → columns render but **headers vanish, sort breaks** (Vuetify 3 ignores them). No JS error — only visible in a rendered screenshot.
+
+### `t-*` columns in V3 must declare `v-model`
+
+V2 adds `v-model="item['{value}']"` to every column with `el` by itself. **V3 does not**: a `t-num`/`t-time`/`t-label`… column without `attr["v-model"]` gets an empty value. `t-num` then gets 0, which `hidezero` hides, so **the whole column is blank with no error anywhere** (measured on the real V3 framework). Headers the table builds itself (no `:headers`) already have `v-model`.
+
+```json
+// V3 ✅
+{ "title": "Số lượng", "key": "SoLuong", "el": "t-num", "attr": { "v-model": "item.SoLuong" } }
+```
 
-### Props bổ sung ở V3
+### Extra V3 props
 
-| Prop | Mặc định V3 | Ghi chú |
-|---|---|---|
-| `density` | `'compact'` | Mật độ dòng — `'compact'`/`'comfortable'`/`'default'` |
-| `disable-sort` | `false` | Tắt sort toàn bảng |
-| `slots` | `null` | Custom slot động (object `{ name, html }`) |
-| `group-template` | `null` | Template cho nhóm gộp (`groupBy`) |
-| `height` | `null` | Giống V2: null/bỏ trống = tự giãn; ≤0 = fill đáy; >0 = px cố định |
+| 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 dạng V3
+### sum-format object in V3
 
-Ở V3, key của `sum-format` object phải khớp `key` của header (không phải `value`):
+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" }
 ```
 
-Logic giống V2 hoàn toàn — chỉ khác ở chỗ V3 đọc `col.key` thay vì `col.value` nên tên field phải nhất quán.
+Otherwise identical to V2.