@fui-org/fui-cli 2.1.3 → 2.2.0

package/skills/{fui-skill → fui}/references/component-table.md

@@ -1,287 +1,287 @@
-# FUI Table Components (Source-Based)
-
-> 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).
-
-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).
-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": {
-    ":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" }
-  }
-}
-```
-
-### 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`
-
-### 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.
-
-### `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" } }
-```
-
-### 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.
+# FUI Table Components (Source-Based)
+
+> 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).
+
+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).
+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": {
+    ":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" }
+  }
+}
+```
+
+### 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`
+
+### 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.
+
+### `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" } }
+```
+
+### 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.