@fui-org/fui-cli 1.3.2 → 2.0.0

package/skills/fui-skill/references/fastproject.md

@@ -1,97 +1,99 @@
 # FastProject (Core Framework)
 
-> File này sở hữu: **bootstrapper `fastproject.js`: vòng đời khởi tạo project/module**. Bản đồ toàn bộ script xem [script-map.md](script-map.md).
+> Owns: **the `fastproject.js` bootstrapper: project/module init lifecycle**. Full script map: [script-map.md](script-map.md).
 
-This document references the core framework logic defined in `fastproject.js`. This script is responsible for initializing the application, building the UI from JSON configurations, and handling the logic engine.
+`fastproject.js` initializes the app, builds UI from JSON config, and runs the logic engine.
 
 ## Global State
 
 ### vueData
-The central reactive state object for the application.
-- `p_domain`, `p_routers`, `p_params`: Routing and environment info.
-- `user`: Current user information.
-- `v_Set`: Application settings (title, menu, attributes).
-- `v_Loading`: Global loading state.
+
+Central reactive state.
+
+- `p_domain`, `p_routers`, `p_params`: routing and environment.
+- `user`: current user.
+- `v_Set`: app settings (title, menu, attributes).
+- `v_Loading`: global loading state.
 
 ### vueOBJ
-The Vue instance configuration object.
+
+Vue instance config object.
 
 ## Core Functions
 
 ### loadModuleInfo()
-Initializes the module by:
-1. Loading project and module settings.
-2. Building URL parameters.
-3. Fetching user info (if configured).
-4. Calling `createModuleDom()`.
+
+1. Load project and module settings.
+2. Build URL parameters.
+3. Fetch user info (if configured).
+4. Call `createModuleDom()`.
 
 ### createModuleDom()
-Builds the Vue application structure:
-1. Executes initial data actions (`$moduleUI.data`).
-2. Generates the HTML structure using `buildModuleUI`.
-3. Initializes Vue watchers and WebSocket connections.
-4. Mounts the Vue instance.
+
+1. Run initial data actions (`$moduleUI.data`).
+2. Generate HTML via `buildModuleUI`.
+3. Init Vue watchers and WebSocket connections.
+4. Mount the Vue instance.
 
 ### buildModuleUI(controlsList, target)
-Recursively builds the DOM structure from a JSON list of controls.
-- **Parameters:**
-  - `controlsList` (Array): List of control definitions.
-  - `target` (Object): Target object for data binding (usually `vueData`).
-- **Returns:** jQuery object containing the generated HTML.
+
+Recursively builds DOM from a JSON control list.
+
+- `controlsList` (Array): control definitions.
+- `target` (Object): binding target (usually `vueData`).
+- Returns: jQuery object with the generated HTML.
 
 ### buildControl(controlsList, flex, target)
-Helper function for `buildModuleUI` to generate individual controls.
-- Supports grid layout (`v-layout`, `v-flex`) and nested components.
-- Handles attribute binding and event mapping.
+
+`buildModuleUI` helper for individual controls.
+
+- Grid layout (`v-layout`, `v-flex`) and nested components.
+- Attribute binding and event mapping.
 
 ### runAction(obj, includeData)
-The central logic engine. Executes a sequence of actions defined in JSON.
-- **Parameters:**
-  - `obj` (Object|Array): The action(s) to execute.
-  - `includeData` (Object): Context data.
-- **Supported Action Types:**
-  - `CONFIRM`: Show confirmation dialog.
-  - `API`: Call an API.
-  - `CALL`: Recursive call to another action.
-  - `EXE`: Execute raw JavaScript.
-  - `FUN`: Call a global function.
-  - `IF/THEN/ELSE`: Conditional logic.
-  - `MESS`/`MESSBOX`: Show messages.
-  - `IN`/`OUT`: Data mapping.
+
+Central logic engine; runs a JSON action sequence.
+
+- `obj` (Object|Array): action(s).
+- `includeData` (Object): context data.
+- Action types: `CONFIRM` (confirm dialog), `API` (call API), `CALL` (another action, recursive), `EXE` (raw JS), `FUN` (global function), `IF/THEN/ELSE`, `MESS`/`MESSBOX` (messages), `IN`/`OUT` (data mapping).
 
 ### vueAction(objAction, includeData, callBack)
-Internal function used by `runAction` to execute a single action step.
+
+Internal; runs a single action step for `runAction`.
 
 ### callAPI(objApi, callBack, includeData)
-Executes an API call defined in a JSON action object.
-- Handles `BEFORE`, `AFTER` actions, and success/error callbacks.
-- Automatically maps response data to `vueData` if `OUT` is specified.
+
+Runs an API call from a JSON action.
+
+- Handles `BEFORE`, `AFTER` actions, success/error callbacks.
+- Maps response into `vueData` when `OUT` is set.
 
 ### mapData(map, target, src, includeData)
-Maps data from a source object to a target object based on a mapping definition.
-- Supports cross-window data mapping using `#PARENT` or window IDs.
-- **Parameters:**
-  - `map` (Object|String): Mapping definition.
-  - `target` (Object): Destination object.
-  - `src` (Object): Source object.
+
+Maps source → target by a mapping definition.
+
+- Cross-window mapping via `#PARENT` or window IDs.
+- `map` (Object|String): mapping; `target` (Object): destination; `src` (Object): source.
 
 ### getVueData(key, src)
-Resolves a value from a key string, supporting deep paths and template syntax (e.g., `{{user.Name}}`).
+
+Resolves a value from a key string; deep paths and template syntax (e.g. `{{user.Name}}`).
 
 ### bindData(obj)
-Resolves all dynamic values within an object.
+
+Resolves all dynamic values in an object.
 
 ### createWatch(obj)
-Sets up Vue watchers based on a JSON configuration.
-- Supports deep watching.
-- Executes actions when watched values change.
+
+Vue watchers from JSON config; supports deep watch; runs actions on change.
 
 ### loginFUN()
-Handles user login redirection.
-- Opens a login window or redirects to the login page.
+
+Login redirect: opens a login window or redirects to the login page.
 
 ### errorMess(code, message)
-Displays standard error messages based on HTTP status codes.
-- **Parameters:**
-  - `code` (String|Number): HTTP status code.
-  - `message` (String): Custom error message.
+
+Standard error message by HTTP status.
+
+- `code` (String|Number): HTTP status; `message` (String): custom message.

package/skills/fui-skill/references/fsheet.md

@@ -1,183 +1,168 @@
-# f-sheet — Bảng tính nhập liệu (dựa trên AG Grid)
+# f-sheet — Data-Entry Grid (AG Grid)
 
-> File này sở hữu: **`f-sheet` (AG Grid): import, props, cấu hình cột, cell renderer dựng sẵn, chọn vùng/fill/clipboard, wiring API**.
+> Owns: **`f-sheet` (AG Grid): import, props, columns, built-in cell renderers, range select/fill/clipboard, API wiring**.
 
-`f-sheet` là **data grid nhập liệu kiểu Excel**, xây dựng **hoàn toàn trên AG Grid Community**. Mọi cấu hình cột/lưới đều là cấu hình AG Grid — **khi cần tuỳ biến, dựa vào kiến thức AG Grid** (https://www.ag-grid.com/, phiên bản Community). FUI chỉ bọc thêm: toolbar (thêm/xoá/lưu/xuất Excel), theo dõi dòng thay đổi, chọn vùng nhiều ô kiểu Excel + fill handle + copy/paste TSV, và wiring API.
+Excel-style entry grid, **entirely AG Grid Community** — customize with AG Grid knowledge (https://www.ag-grid.com/, Community). FUI adds: toolbar (add/delete/save/export Excel), change tracking, range select + fill handle + TSV copy/paste, API wiring.
 
-> **Phân biệt với `f-table`**: `f-table` hiển thị dữ liệu dạng datatable, sửa dòng qua dialog form riêng. `f-sheet` sửa **ngay trên ô của bảng** (không qua dialog), phù hợp nhập liệu hàng loạt kiểu Excel (dán nhiều dòng, sửa nhanh nhiều ô). Cùng là component có sẵn — không tự viết bảng nhập liệu bằng `uc-*.vue`.
+> **vs `f-table`** (rows edited via dialog form): `f-sheet` edits **in cells**, for bulk entry (paste rows, fast multi-cell edits). Never hand-write an entry grid as `uc-*.vue`.
 
-> Nền tảng (nguồn sự thật): `scripts/fsheet.js` — **một file DUY NHẤT dùng chung cho cả V2 và V3** (không còn khái niệm 2 bản phải giữ đồng bộ). Component khai cả `beforeDestroy` (Vue 2) lẫn `beforeUnmount` (Vue 3) để hoạt động đúng trên cả hai runtime. Template dùng thuần class/prop **Vuetify 3** (`variant="text"`, `density="comfortable"`, `text-primary`, `text-subtitle-1`, `text-caption`) — trên module V2 (Vuetify 2) toolbar vẫn bấm được nhưng có thể không lên đúng màu/kiểu vì Vuetify 2 bỏ qua các prop/class lạ này. Dùng `ajaxCALL`/`confirm`/`jsonToExcel` bên trong — khớp [component-design.md](component-design.md) §12.
+> Source: `scripts/fsheet.js`, **one file for V2 and V3** (`beforeDestroy` + `beforeUnmount`). Template uses **Vuetify 3** props/classes (`variant="text"`, `density="comfortable"`, `text-primary`, `text-subtitle-1`, `text-caption`); on V2 the toolbar works but styling may be off. Uses `ajaxCALL`/`confirm`/`jsonToExcel` ([component-design.md](component-design.md) §12).
 
 ---
 
-## Import BẮT BUỘC (thiếu → không dùng được f-sheet)
+## Required import
 
-Thêm đúng 2 file, **đúng thứ tự**, qua `file_import_new`:
+Exactly 2 files, **in this order**, via `fui import new` (missing → unusable):
 
 ```
 /include/ag-grid/ag-grid-community.min.js
 /include/ag-grid/fsheet.js
 ```
 
-Quy trình khi thêm/bỏ f-sheet: `file_import_list` (projectId + moduleId) → chưa có thì `file_import_new` từng file → bỏ f-sheet mà không module/component khác dùng thì `file_import_delete`. Xem [component-quickref.md](component-quickref.md).
+`fui import list` (projectId + moduleId) → `fui import new` missing ones; removing f-sheet and nothing else uses them → `fui import delete`. See [component-quickref.md](component-quickref.md).
 
 ---
 
 ## Props
 
-| Prop (kebab-case trong `attr`) | Kiểu | Ý nghĩa |
-|---|---|---|
-| `label` | string | Tiêu đề + hiện trên thanh công cụ |
-| `:columns` | array | **colDefs của AG Grid** (xem mục Cột). Bỏ trống → tự suy cột từ `items[0]` (mỗi field → `{ field, headerName: field }`) |
-| `:items` | array | Dữ liệu dòng (rowData) |
-| `row-key` | string | Tên field khóa chính (mặc định `id`) — dùng để nhận diện dòng đổi/mới/xoá |
-| `:height` | number | Bỏ trống = tự giãn theo số dòng; `<=0` = fill tới đáy màn hình chừa `abs(height)` px; `>0` = px cố định (xem mục Chiều cao) |
-| `:allow-add` | bool | Hiện nút Thêm dòng |
-| `:allow-delete` | bool | Hiện cột checkbox chọn + nút Xoá |
-| `readonly` | bool | Khoá toàn bộ chỉnh sửa (đồng thời tắt luôn fill handle) |
-| `update-api` | string | Endpoint tAPI **lưu từng dòng đã đổi** (gọi qua `ajaxCALL`, tự prepend `apiDomain`). Không khai thì nút Lưu bị `disabled` |
-| `delete-api` | string | Endpoint tAPI xoá một dòng |
-| `:save-extra` | object | Tham số phụ **trộn vào payload** mỗi lần lưu/xoá (vd `{ LopID: vueData.lopID }`) — đi qua `mapData`, hỗ trợ tham chiếu động `vueData.x` |
-| `:default-item` | object | Mẫu giá trị cho dòng mới khi bấm Thêm — cũng đi qua `mapData`, hỗ trợ tham chiếu động `vueData.x`, không chỉ literal tĩnh |
+| Prop (kebab-case in `attr`) | Type   | Meaning                                                                                                                              |
+| --------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `label`                     | string | Title, shown on toolbar                                                                                                              |
+| `:columns`                  | array  | **AG Grid colDefs**. Empty → inferred from `items[0]` (`{ field, headerName: field }`)                                               |
+| `:items`                    | array  | rowData                                                                                                                              |
+| `row-key`                   | string | PK field (default `id`) — tracks changed/new/deleted rows                                                                            |
+| `:height`                   | number | empty = auto-grow; `<=0` = fill to screen bottom leaving `abs(height)` px; `>0` = fixed px                                           |
+| `:allow-add`                | bool   | Add row button                                                                                                                       |
+| `:allow-delete`             | bool   | Checkbox column + Delete button                                                                                                      |
+| `readonly`                  | bool   | Lock all editing (also fill handle)                                                                                                  |
+| `update-api`                | string | tAPI endpoint **saving each changed row** (`ajaxCALL`, auto-prepends `apiDomain`). Missing → Save `disabled`                         |
+| `delete-api`                | string | tAPI endpoint deleting one row                                                                                                       |
+| `:save-extra`               | object | Extra params **merged into every save/delete payload** (e.g. `{ LopID: vueData.lopID }`); via `mapData`, dynamic `vueData.x` allowed |
+| `:default-item`             | object | New-row template on Add; via `mapData`, dynamic `vueData.x` allowed (not only literals)                                              |
 
 ---
 
-## Cột (`columns`) = colDef của AG Grid
+## Columns = AG Grid colDef
 
-Mỗi phần tử `columns` là một **AG Grid colDef** — dùng trực tiếp kiến thức AG Grid:
+| Key                                 | Meaning                                                                                         |
+| ----------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `field` / `headerName`              | data field / label                                                                              |
+| `editable`                          | **on by default** (`defaultColDef.editable: !readonly`); read-only column → `"editable": false` |
+| `width` / `minWidth` / `flex`       | default `flex:1`, `minWidth:80`                                                                 |
+| `pinned`                            | `'left'`/`'right'`                                                                              |
+| `sortable` / `filter` / `resizable` | all on by default                                                                               |
+| `valueFormatter` / `valueGetter`    | AG Grid functions                                                                               |
+| `cellEditor`                        | AG Grid built-in name (e.g. `agDateStringCellEditor`) or own global function name               |
+| `cellRenderer`                      | one of 4 f-sheet built-ins (below) or own global function name                                  |
+| `type`                              | **registered columnType name — only `"number"` / `"date"`**, not a free data type               |
 
-| Key colDef hay dùng | Ý nghĩa |
-|---|---|
-| `field` | Tên field trong dòng dữ liệu |
-| `headerName` | Nhãn cột |
-| `editable` | Cho sửa ô — **mặc định bật** (f-sheet đặt `editable: !readonly` trong `defaultColDef`); cột chỉ đọc khai `"editable": false` |
-| `width` / `minWidth` / `flex` | Bề rộng cột (mặc định `flex:1`, `minWidth:80`) |
-| `pinned` | `'left'`/`'right'` cố định cột |
-| `sortable` / `filter` / `resizable` | Mặc định đều bật |
-| `valueFormatter` / `valueGetter` | Định dạng/hiển thị (hàm AG Grid) |
-| `cellEditor` | Editor tuỳ chỉnh — tên có sẵn của AG Grid (vd `agDateStringCellEditor`) hoặc tên hàm global tự viết |
-| `cellRenderer` | Renderer tuỳ chỉnh — 4 renderer dựng sẵn của f-sheet (xem bên dưới) hoặc tên hàm global tự viết |
-| `type` | **Tên columnType đã đăng ký** — chỉ có `"number"` và `"date"`. **KHÔNG phải** chỗ khai kiểu dữ liệu tự do (xem mục columnType ngay dưới) |
+Other features (cellClassRules, aggregation...) → AG Grid docs; colDef passes straight through.
 
-> Các tính năng cột nâng cao khác (cellClassRules, aggregation...) tra tài liệu AG Grid Community — f-sheet truyền colDef thẳng vào grid. Riêng cột `type:"number"`/`type:"date"` được f-sheet **tự gắn** `cellStyle`/`valueFormatter`/`valueParser`/`filter` (xem bên dưới) — chỉ khai tay khi cần logic khác mặc định.
+### columnType: only `number` and `date`
 
-### columnType — f-sheet đăng ký ĐÚNG 2 tên: `number` và `date`
+`type` references `gridOptions.columnTypes`; only two registered (`FS_COLUMN_TYPES`, top of `scripts/fsheet.js`). Unregistered name (`"date_time"`, `"currency"`, `"text"`, `"string"`, `"boolean"`…):
 
-`type` **không phải** key gốc của AG Grid dùng để khai kiểu dữ liệu. Nó là **tên tham chiếu tới một columnType đã đăng ký** trong `gridOptions.columnTypes`. f-sheet đăng ký đúng hai tên — bảng `FS_COLUMN_TYPES` ở đầu `scripts/fsheet.js` là nguồn duy nhất.
+- AG Grid **ignores it** (logs only `warning #36 colDef.type 'x' does not correspond to defined gridOptions.columnTypes`) → raw text, **no** format/parse/filter.
+- f-sheet adds a `console.error` naming column + valid names (scans group `children` too) — **visible in `fui module simulate --render`**; AG Grid's warning isn't.
 
-Đặt một tên **chưa đăng ký** (`"date_time"`, `"currency"`, `"text"`, `"string"`, `"boolean"`…) thì:
+Other types (currency, percent, datetime…) → declare `valueFormatter`/`valueParser`/`filter` on the colDef, never a new `type`.
 
-- AG Grid **bỏ qua hoàn toàn** và chỉ log `warning #36 colDef.type 'x' does not correspond to defined gridOptions.columnTypes` — cột chạy y hệt cột text thô, **không** format, **không** parse, **không** filter. Cấu hình trông như có tác dụng nhưng không có.
-- f-sheet phát thêm một `console.error` nêu đích danh tên cột + danh sách tên hợp lệ (quét cả colDef nằm trong `children` của column group). Dòng này **hiện lên trong `module_simulate({ renderUI: true })`** — warning gốc của AG Grid thì không.
+### Built-in cell renderers
 
-Cần một kiểu khác hai kiểu trên (tiền tệ, phần trăm, ngày-giờ…) thì **đừng đặt tên mới cho `type`** — khai thẳng `valueFormatter`/`valueParser`/`filter` trên colDef đó.
+Use `"cellRenderer": "name"` + `cellRendererParams`; nothing to declare in `script.js`:
 
-### Cell renderer dựng sẵn (`cellRenderer`)
+| Renderer               | Purpose                                  | `cellRendererParams`                                                                                                                                                                                       |
+| ---------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `fsHtmlCellRenderer`   | raw HTML `value` (like f-table `t-html`) | _(none)_                                                                                                                                                                                                   |
+| `fsLinkCellRenderer`   | link                                     | `urlField`/`textField` (row field for URL/label, default `value`), `icon` (mdi, optional), `target`: `'dialog'` → `openWindow({id: wid, title, url, onclose})`, else `<a>` target (default `_blank`)       |
+| `fsButtonCellRenderer` | small button                             | `label`, `icon` (mdi, optional), `color` (default `#1976d2`); click: `url` → `openWindow({id: wid, title, url, onclose})`, no `url` → `tableActionEvent({action, item: data})`                             |
+| `fsMenuCellRenderer`   | `⋮` per-row dropdown                     | `items`: array `{icon, text, color, action}` or `function(params)` returning it (per-row); `icon` for trigger (default `mdi-dots-vertical`). Click → `tableActionEvent({action: item.action, item: data})` |
 
-f-sheet đăng ký sẵn 4 renderer — dùng ngay qua `"cellRenderer": "tênRenderer"` + `cellRendererParams`, không cần khai gì thêm trong `script.js`:
+`openWindow`/`tableActionEvent` are FUI globals (as in f-table `t-link`/`t-button`/`t-menu`). **Own global functions** also work for `cellRenderer`/`cellEditor`/`cellEditorParams`/`cellRendererParams`: define in `script.js`, reference by string name; auto-registered (incl. group `children`).
 
-| Renderer | Mục đích | `cellRendererParams` |
-|---|---|---|
-| `fsHtmlCellRenderer` | In `value` ra dạng HTML thô (giống `t-html` của f-table) | *(không cần)* |
-| `fsLinkCellRenderer` | Ô dạng link | `urlField`/`textField` (field khác trong dòng làm URL/nhãn, mặc định dùng `value`), `icon` (mdi, tuỳ chọn), `target` — `'dialog'` mở qua `openWindow({id: wid, title, url, onclose})`, còn lại là target của thẻ `<a>` (mặc định `_blank`) |
-| `fsButtonCellRenderer` | Ô dạng nút bấm nhỏ | `label`, `icon` (mdi, tuỳ chọn), `color` (mặc định `#1976d2`); bấm vào: có `url` → `openWindow({id: wid, title, url, onclose})`, không có `url` → `tableActionEvent({action, item: data})` (action đặt tên trong `action`) |
-| `fsMenuCellRenderer` | Nút `⋮` mở menu thả xuống theo dòng | `items` — mảng `{icon, text, color, action}` hoặc hàm `function(params)` trả về mảng đó (để tính động theo dòng); `icon` cho nút mở menu (mặc định `mdi-dots-vertical`). Bấm một item → `tableActionEvent({action: item.action, item: data})` |
+### `"type": "number"` — auto-attached (only if colDef doesn't declare it)
 
-`fsButtonCellRenderer`/`fsMenuCellRenderer` dùng lại `openWindow`/`tableActionEvent` — 2 hàm global gốc của FUI (giống hệt cách `t-link`/`t-button`/`t-menu` của `f-table` hoạt động), không phải cơ chế riêng của f-sheet.
+| Key              | Behavior                                                                                                             |
+| ---------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `cellStyle`      | right-aligned                                                                                                        |
+| `valueFormatter` | `toLocaleString('en-US', { maximumFractionDigits: 10 })` → `1,234,567.89`; **display only**, editor shows raw number |
+| `valueParser`    | empty/`null`/`undefined` → real `null` (not `""`); numeric string → `Number`; invalid → `null`. Also on Excel paste  |
+| `filter`         | `agNumberColumnFilter`                                                                                               |
 
-**Tên hàm global tự viết** cũng dùng được trực tiếp cho cả `cellRenderer`/`cellEditor` lẫn `cellEditorParams`/`cellRendererParams` — khai hàm đó trong `script.js` của module rồi tham chiếu bằng tên (string). f-sheet tự nhận diện và đăng ký (kể cả khi colDef nằm trong `children` của một column group), không cần đăng ký thủ công.
+### `"type": "date"` — auto-attached (only if colDef doesn't declare it)
 
-### Cột số — `"type": "number"`
+| Key              | Behavior                                                                                                                                       |
+| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `cellStyle`      | centered                                                                                                                                       |
+| `valueFormatter` | `dd/mm/yyyy`; non-date → **raw string** shown (junk stays visible)                                                                             |
+| `valueParser`    | accepts `dd/mm/yyyy`, `dd-mm-yyyy`, `yyyy-mm-dd`, ISO `2026-08-15T00:00:00` → stores `yyyy-mm-dd`; empty/invalid → `null`. Also on Excel paste |
+| `filter`         | `agDateColumnFilter`                                                                                                                           |
 
-Khai `"type": "number"` là đủ, f-sheet tự gắn 4 thứ (mỗi thứ chỉ gắn khi colDef **chưa** tự khai, nên muốn khác mặc định thì cứ khai đè):
+**Value contract (what the SP gets):** **`yyyy-mm-dd`** or `null` — matches `f-date` and tAPI `OPENJSON ... NgayX date '$.NgayX'`. Invalid (`31/02/2026`, `15/13/2026`) → `null`, no rollover. **Copy/Excel export use the raw value** (`2026-08-15`) — intentional, lossless round-trip.
 
-| Tự gắn | Hành vi |
-|---|---|
-| `cellStyle` | Canh **phải** |
-| `valueFormatter` | Phân cách nghìn `toLocaleString('en-US', { maximumFractionDigits: 10 })` → `1,234,567.89`. Chỉ áp lúc **hiển thị** — click vào ô sửa vẫn thấy số thô |
-| `valueParser` | Parse khi rời ô sửa: rỗng/`null`/`undefined` → `null` thật (không phải `""`), chuỗi số → `Number`, chuỗi hỏng → `null`. Áp cho cả paste-từ-Excel |
-| `filter` | `agNumberColumnFilter` (lọc lớn hơn/nhỏ hơn/bằng thay vì lọc text) |
+#### Date picker
 
-### Cột ngày — `"type": "date"`
-
-Khai `"type": "date"` là đủ, f-sheet tự gắn 4 thứ (mỗi thứ chỉ gắn khi colDef **chưa** tự khai):
-
-| Tự gắn | Hành vi |
-|---|---|
-| `cellStyle` | Canh **giữa** |
-| `valueFormatter` | Hiển thị `dd/mm/yyyy`. Giá trị không phải ngày → in **chuỗi thô** (để dữ liệu rác hiện ra, không biến ô thành trống) |
-| `valueParser` | Nhận `dd/mm/yyyy`, `dd-mm-yyyy`, `yyyy-mm-dd` và ISO datetime `2026-08-15T00:00:00` → lưu `yyyy-mm-dd`. Rỗng → `null`. Sai → `null`. Áp cho cả paste-từ-Excel |
-| `filter` | `agDateColumnFilter` (lọc trước/sau/bằng ngày) |
-
-**Hợp đồng giá trị — đây là thứ quyết định SP nhận được gì:** ô ngày luôn giữ chuỗi **`yyyy-mm-dd`** (hoặc `null`). Khớp thẳng với `f-date` (cũng emit `yyyy-mm-dd`) và với `OPENJSON ... NgayX date '$.NgayX'` phía tAPI — không phải convert gì thêm.
-
-- **Ngày không hợp lệ về `null`, ô thành rỗng** — giống hệt cột số. `31/02/2026` và `15/13/2026` bị từ chối (không âm thầm cuộn sang `03/03/2026` / `15/01/2027`).
-- **Copy và Xuất Excel lấy giá trị thô** ⇒ ra `2026-08-15`, không phải `15/08/2026`. Cố ý: dán ngược vào lưới thì parse lại được, round-trip không mất mát.
-
-#### Muốn có date picker
-
-`type: "date"` lo hiển thị/parse/lọc, **không tự gắn editor** — sửa ô vẫn là gõ text. Cần picker thì khai thêm:
+`type: "date"` adds **no editor** (text typing). For a picker:
 
 ```json
 { "field": "NgayThi", "headerName": "Ngày thi", "type": "date", "cellEditor": "agDateStringCellEditor" }
 ```
 
-`agDateStringCellEditor` là editor **có sẵn của AG Grid**, không cần đăng ký gì. Nhưng nó đọc **giá trị thô** chứ không qua `valueFormatter`, nên ô đang giữ ISO datetime (`2026-08-15T00:00:00`) sẽ mở ra **rỗng** cho tới khi được sửa một lần. Cho SP trả `CONVERT(date, NgayThi)` là hết — cũng là lý do f-sheet không gắn editor này mặc định (gắn ngầm thì bấm Enter là ghi `null` đè lên ngày đang có).
+AG Grid built-in. Reads the **raw value**: ISO datetime (`2026-08-15T00:00:00`) opens **empty** until edited once → SP returns `CONVERT(date, NgayThi)`. Not attached by default because Enter would write `null` over the date.
 
-> **Không có editor nào tên `fsheetDate`.** Tên đó **từng tồn tại** trong `componentTable*.js` rồi `fsheet.js` và **đã bị gỡ**. Module cũ còn khai `"cellEditor": "fsheetDate"` thì đổi sang `"type": "date"` (thêm `agDateStringCellEditor` nếu cần picker). Luật nền cần nhớ: `cellEditor`/`cellRenderer` dạng string chỉ resolve được khi `window[tên]` là một function — tên không tồn tại thì f-sheet **im lặng** bỏ qua và AG Grid rơi về editor text, không lỗi, không cảnh báo.
+> **`fsheetDate` was removed.** Old `"cellEditor": "fsheetDate"` → `"type": "date"` (+ `agDateStringCellEditor`). String `cellEditor`/`cellRenderer` resolves only if `window[name]` is a function; unknown names **silently** fall back to the text editor.
 
-### Chiều cao — `:height`
+### `:height`
 
-| Giá trị | Hành vi |
-|---|---|
-| *(bỏ trống)* | **Tự giãn theo số dòng** — AG Grid `domLayout: 'autoHeight'`, lưới cao bằng đúng nội dung, không có thanh cuộn riêng |
-| `<= 0` | **Fill tới đáy màn hình, chừa `abs(height)` px** |
-| `> 0` | px cố định (vd `":height": 300`) |
+| Value     | Behavior                                                      |
+| --------- | ------------------------------------------------------------- |
+| _(empty)_ | **auto-grow** — `domLayout: 'autoHeight'`, no inner scrollbar |
+| `<= 0`    | **fill to screen bottom, leaving `abs(height)` px**           |
+| `> 0`     | fixed px (e.g. `":height": 300`)                              |
 
-Chế độ `<=0` **đo `getBoundingClientRect().top` thật** của phần tử lưới sau khi layout xong rồi tính `window.innerHeight - top - abs(height)` (sàn tối thiểu 200px), và đăng ký `window.resize` để tự cập nhật. Nghĩa là **không cần biết** header/toolbar/breadcrumb phía trên cao bao nhiêu — chỉ khai khoảng hở muốn chừa ở đáy.
+`<=0` = `window.innerHeight - getBoundingClientRect().top - abs(height)` (min 200px), measured after layout, updated on `window.resize` — only the bottom gap matters.
 
-- **Bảng chính của module**: khai `":height": -16` — cuộn data chỉ cuộn trong lưới, trang không cuộn (lint D9). Thiếu `:height` sẽ bị D9 cảnh báo.
-- **Trong dialog**: dùng số **dương** (px cố định), vì lưới không nằm sát đáy viewport.
-- **Bảng ngắn/lookup ít dòng**: bỏ trống `:height` để tự giãn — hợp lệ, bỏ qua D9.
-- ⚠ Chế độ tự giãn **render toàn bộ dòng** (AG Grid không ảo hoá được khi không có chiều cao cố định). Vài trăm dòng trở lên thì phải khai `:height` để lấy lại virtual scrolling.
-- ⚠ Số âm **không** có nghĩa "viewport trừ đi N". Module cũ khai `":height": -220` phải sửa thành `-16`, nếu không lưới hụt mất ~200px.
+- Main table: `":height": -16` (scrolls inside grid; lint D9 warns if `:height` missing).
+- Dialog: **positive** px.
+- Short/lookup tables: omit (auto-grow, exempt from D9). ⚠ Auto-grow renders every row, no virtualization — hundreds of rows → set `:height`.
+- ⚠ Negative ≠ "viewport minus N": old `-220` → `-16`, else ~200px short.
 
 ---
 
-## Wiring API — hợp đồng response
+## API wiring — response contract
 
-`update-api` và `delete-api` được gọi bằng `ajaxCALL(api, { ...saveExtra, ...row })`. **SP nên trả về một dòng** dạng:
+Called as `ajaxCALL(api, { ...saveExtra, ...row })`. **SP returns one row:**
 
 ```
 SELECT Success = 1, Message = N'Đã lưu'      -- hoặc Success = 0 khi lỗi nghiệp vụ
 ```
 
-f-sheet đọc `res.data[0]` → hiện snackbar `Message`; `Success` quyết định đánh dấu thành công. Xem quy ước SP: [tapi-reference.md](tapi-reference.md).
+Reads `res.data[0]`: `Message` → snackbar, `Success` → marks success. See [tapi-reference.md](tapi-reference.md).
 
-- **Dòng mới**: nhận khóa **âm** tạm (−1, −2…) và tô nền **xanh nhạt**; khi lưu, khóa âm được đặt `0` trong payload → SP hiểu là INSERT.
-- **Ô đã sửa**: tô nền **vàng nhạt**; "N dòng thay đổi" hiển thị trên toolbar.
-- Lưu chạy **từng dòng song song**; xong hết & không lỗi → làm mới baseline, xoá đánh dấu, emit `saved`.
-- Xoá nhiều dòng đã tồn tại (đã khai `delete-api`) → hỏi `confirm` trước rồi mới gọi API cho từng dòng; **chưa khai `delete-api`** thì xoá cục bộ ngay, không hỏi. Dòng mới (khóa âm) luôn xoá cục bộ ngay, không hỏi, không gọi API.
+- **New rows**: temp **negative** key (−1, −2…), **light green**; on save key → `0` in payload → SP INSERTs.
+- **Edited cells**: **light yellow**; toolbar shows "N rows changed".
+- Save runs **per row, in parallel**; all OK → baseline refreshed, marks cleared, `saved` emitted.
+- Delete existing rows: with `delete-api` → `confirm`, then API per row; without → local, no prompt. New rows → always local, no prompt, no API.
 
 ---
 
-## Tính năng có sẵn (không cần tự code)
+## Built-in (don't code)
 
-- **Sửa inline** + theo dõi thay đổi (vàng nhạt = ô đã đổi, xanh nhạt = dòng mới).
-- **Chọn nhiều ô kiểu Excel**: kéo chuột hoặc Shift+click để chọn một khối ô liên tục.
-- **Fill handle**: kéo núm vuông ở góc dưới-phải vùng đang chọn để điền lặp lại khối nguồn sang các ô lân cận (theo chiều kéo dài hơn — ngang hoặc dọc).
-- **Copy/Cut/Paste dạng TSV** (tương thích Excel/Google Sheets): phím tắt Ctrl+C/Ctrl+X/Ctrl+V khi đang focus trong lưới, hoặc menu chuột phải (Cut/Copy/Copy with Headers/Paste).
-- **Phím Escape** bỏ vùng đang chọn.
-- Toolbar: **Xuất Excel** (luôn có, dùng `jsonToExcel`) · **Thêm** (`allow-add`) · **Lưu** (hiện khi có dòng đổi, `disabled` nếu chưa khai `update-api`) · **Huỷ thay đổi** (hiện khi có dòng đổi) · **Xoá đã chọn** (`allow-delete`, multi-select, chỉ hiện khi có dòng đang chọn).
+- Inline edit + change tracking.
+- Range select: drag or Shift+click.
+- Fill handle: drag bottom-right square to repeat the source block (along the longer drag direction).
+- TSV Copy/Cut/Paste (Excel/Google Sheets): Ctrl+C/X/V in grid, or right-click (Cut/Copy/Copy with Headers/Paste).
+- Escape clears selection.
+- Toolbar: **Export Excel** (always, `jsonToExcel`) · **Add** (`allow-add`) · **Save** (when changes; `disabled` without `update-api`) · **Discard changes** (when changes) · **Delete selected** (`allow-delete`, multi-select, only with selection).
 
-## Events & method (`$refs`)
+## Events & methods (`$refs`)
 
-- Emit: `change(data, field, value)` (mỗi lần một ô đổi giá trị) · `save(rows)` (bấm Lưu, trước khi gọi API) · `saved` (lưu thành công toàn bộ).
-- Method: `getChangedRows()` · `addRow()` · `deleteRow(row)` · `deleteSelected()` · `discardAll()` · `exportExcel()`.
+- Emit: `change(data, field, value)` (each cell change) · `save(rows)` (Save clicked, before API) · `saved` (all saved).
+- Methods: `getChangedRows()` · `addRow()` · `deleteRow(row)` · `deleteSelected()` · `discardAll()` · `exportExcel()`.
 
 ---
 
-## Ví dụ trong module.json (controls)
+## module.json example
 
 ```json
 {
@@ -188,11 +173,11 @@ f-sheet đọc `res.data[0]` → hiện snackbar `Message`; `Success` quyết đ
     ":items": "dsDiem",
     "row-key": "DiemID",
     ":columns": [
-      { "field": "MaSV",  "headerName": "Mã SV",  "editable": false, "width": 120, "pinned": "left" },
+      { "field": "MaSV", "headerName": "Mã SV", "editable": false, "width": 120, "pinned": "left" },
       { "field": "HoTen", "headerName": "Họ tên", "editable": false },
-      { "field": "Diem",  "headerName": "Điểm",   "type": "number" },
-      { "field": "NgayThi","headerName": "Ngày thi", "type": "date" },
-      { "field": "GhiChu","headerName": "Ghi chú" }
+      { "field": "Diem", "headerName": "Điểm", "type": "number" },
+      { "field": "NgayThi", "headerName": "Ngày thi", "type": "date" },
+      { "field": "GhiChu", "headerName": "Ghi chú" }
     ],
     ":allow-add": true,
     ":allow-delete": true,
@@ -205,14 +190,14 @@ f-sheet đọc `res.data[0]` → hiện snackbar `Message`; `Success` quyết đ
 }
 ```
 
-- `dsDiem` được nạp trước bằng một action trong `data[]` (`API`/`OUT`).
-- `Diem_Save`/`Diem_Delete` là SP tAPI trả `{ Success, Message }` mỗi dòng.
-- Kết hợp mở cửa sổ chi tiết: nút/menu trong toolbar hoặc cột gọi `openWindow` — xem [ui-crosswindow-patterns.md](ui-crosswindow-patterns.md) §5.
+- `dsDiem` loaded first by a `data[]` action (`API`/`OUT`).
+- `Diem_Save`/`Diem_Delete`: tAPI SPs returning `{ Success, Message }` per row.
+- Detail window from toolbar/column button/menu → `openWindow`: [ui-crosswindow-patterns.md](ui-crosswindow-patterns.md) §5.
 
 ## Checklist
 
-1. Đã `file_import_new` đủ **2 file AG Grid**, đúng thứ tự (`ag-grid-community.min.js` trước, `fsheet.js` sau).
-2. `row-key` trỏ đúng khóa chính; SP `update-api`/`delete-api` trả `{ Success, Message }`.
-3. Cần tuỳ biến cột → dùng colDef AG Grid; ô dạng link/nút/menu → 4 cell renderer dựng sẵn (`fsHtmlCellRenderer`/`fsLinkCellRenderer`/`fsButtonCellRenderer`/`fsMenuCellRenderer`); số → `type: "number"`, ngày → `type: "date"` (không tự khai `cellStyle`/`valueFormatter`/`valueParser` tay nữa). `type` **chỉ** nhận đúng 2 tên đó — kiểu khác thì khai thẳng `valueFormatter`/`valueParser`, đừng đặt tên `type` mới.
-4. `:height` — bảng chính khai `-16`; trong dialog dùng số **dương**; bỏ trống = tự giãn (chỉ hợp cho bảng ngắn). Số âm = khoảng chừa ở đáy, **không phải** "viewport trừ N".
-5. Đừng tự dựng lại grid/CSS — mọi cấu hình lưới đi qua `columns` (AG Grid); chọn vùng/fill/copy-paste đã có sẵn, không tự viết thêm.
+1. Both **AG Grid files** imported via `fui import new`, in order (`ag-grid-community.min.js` then `fsheet.js`).
+2. `row-key` = real PK; `update-api`/`delete-api` SPs return `{ Success, Message }`.
+3. AG Grid colDef; link/button/menu → 4 built-in renderers; `type: "number"`/`"date"` only (no manual `cellStyle`/`valueFormatter`/`valueParser`); other types → `valueFormatter`/`valueParser`.
+4. `:height`: main `-16`, dialog positive, empty only for short tables.
+5. Don't rebuild grid/CSS — config via `columns`; range select/fill/copy-paste are built in.