@fui-org/fui-cli 1.3.1 → 2.0.0

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

@@ -1,14 +1,13 @@
 # FUI Input & Interaction Components
 
-> File này sở hữu: **component nhập liệu: `f-date`, `f-time`, `f-search`, `f-radiobox`, `f-button`, `f-menu`, upload**.
+> Owns: **input components: `f-date`, `f-time`, `f-search`, `f-radiobox`, `f-button`, `f-menu`, upload**.
 
-Components dùng để nhận input hoặc tương tác với người dùng. Xem prefix/binding rules tại [components-display.md](components-display.md).
+Components for input and user interaction. Prefix/binding rules: [components-display.md](components-display.md).
 
 ## f-radiobox
 
 - Props (source): `label`, `items`, `itemValue`, `itemText`
 - Emit: `input` on change
-- Example:
 
 ```json
 {
@@ -27,13 +26,11 @@ Components dùng để nhận input hoặc tương tác với người dùng. Xe
 ## f-menu
 
 - Props (source): `items`, `label`, `iconText`, `menuAttr`
-- Behavior: dropdown button với danh sách menu items
-- Nếu `label` rỗng hoặc undefined → hiển thị icon-only button
-- `items` format: mảng `{ text, visible, color, "icon-text", action, href, target }`
-  - `action`: FUI action object — chạy qua `runAction`
-  - `href` + `target`: điều hướng như thẻ `<a>`
-  - `visible`: ẩn/hiện item (default `true`)
-- Example:
+- Dropdown button with menu items; `label` empty/undefined → icon-only button
+- `items`: array of `{ text, visible, color, "icon-text", action, href, target }`
+  - `action`: FUI action object, run via `runAction`
+  - `href` + `target`: navigate like `<a>`
+  - `visible`: show/hide item (default `true`)
 
 ```json
 {
@@ -55,8 +52,7 @@ Components dùng để nhận input hoặc tương tác với người dùng. Xe
 
 - Props (source): `api`, `apiData`, `items`
 - Emit: `input` when selection changes
-- Behavior: debounced API search (500ms), bỏ qua keyword < 2 ký tự
-- Example:
+- Debounced API search (500ms); keywords < 2 chars ignored
 
 ```json
 {
@@ -75,11 +71,8 @@ Components dùng để nhận input hoặc tương tác với người dùng. Xe
 ## f-button
 
 - Props (source): `label`, `checkvalid`, `ctrlhotkey`, `iconText`, `action`, `includeData`
-- Behavior:
-  - debounced click (500ms, leading)
-  - validates form khi `checkvalid=true`
-  - nếu `$attrs.target == 'dialog'`, mở window theo attrs (`wid`, `title`, `url`, `onclose`)
-- Example:
+- Debounced click (500ms, leading); validates form when `checkvalid=true`
+- `$attrs.target == 'dialog'` → opens a window from attrs (`wid`, `title`, `url`, `onclose`)
 
 ```json
 {
@@ -96,12 +89,8 @@ Components dùng để nhận input hoặc tương tác với người dùng. Xe
 ## f-date
 
 - Props (source): `value`, `label`, `dateAdd`, `required`
-- Emit: `input` with normalized date (hoặc `null`)
-- Behavior:
-  - hỗ trợ typed mask và picker
-  - chấp nhận nhiều định dạng input khi khởi tạo
-  - `dateAdd` tự set ngày tương đối so với hôm nay
-- Example:
+- Emit: `input` with normalized date (or `null`)
+- Typed mask + picker; accepts many input formats on init; `dateAdd` sets a date relative to today
 
 ```json
 {
@@ -119,9 +108,8 @@ Components dùng để nhận input hoặc tương tác với người dùng. Xe
 ## f-time
 
 - Props (source): `value`, `label`, `timeAdd`, `required`
-- Emit: `input` with `HH:mm` (hoặc `null`)
-- Behavior: typed mask + time picker
-- Example:
+- Emit: `input` with `HH:mm` (or `null`)
+- Typed mask + time picker
 
 ```json
 {
@@ -139,16 +127,10 @@ Components dùng để nhận input hoặc tương tác với người dùng. Xe
 ## f-time-counter
 
 - Props (source): `value`, `type`, `labelFormat`, `format`
-- `value`: số giây (Number) hoặc datetime string (`"yyyy-MM-dd HH:mm:ss"`)
-- `type`:
-  - `0` — đếm ngược, hiển thị ngày/giờ/phút/giây đầy đủ
-  - `1` — đếm ngược, chỉ hiển thị tổng số giây còn lại
-  - `2` — đồng hồ thời gian thực (hiển thị giờ hiện tại)
-- `format`: `{ label, day, hour, minute, second }` — nhãn đơn vị
-- Emit:
-  - `input` (số giây còn lại) khi đếm từ seconds (value là Number)
-  - `time-end` khi timer về 0
-- Example:
+- `value`: seconds (Number) or datetime string (`"yyyy-MM-dd HH:mm:ss"`)
+- `type`: `0` countdown with full days/hours/minutes/seconds · `1` countdown showing total remaining seconds only · `2` real-time clock (current time)
+- `format`: `{ label, day, hour, minute, second }` — unit labels
+- Emit: `input` (remaining seconds) when counting from seconds (Number value); `time-end` when timer hits 0
 
 ```json
 {
@@ -165,8 +147,7 @@ Components dùng để nhận input hoặc tương tác với người dùng. Xe
 ## f-qrcode
 
 - Props (source): `value`, `logo`, `color`, `size`
-- Behavior: render QR image từ value
-- Example:
+- Renders a QR image from value
 
 ```json
 {
@@ -183,8 +164,7 @@ Components dùng để nhận input hoặc tương tác với người dùng. Xe
 ## f-qrcode-reader
 
 - Props (source): `value`, `label`, `width`
-- Emit: `input` (đóng dialog), `update` (decoded content)
-- Example:
+- Emit: `input` (closes dialog), `update` (decoded content)
 
 ```json
 {
@@ -201,8 +181,7 @@ Components dùng để nhận input hoặc tương tác với người dùng. Xe
 ## f-image-update
 
 - Props (source): `value`, `label`, `title`, `apiUpload`, `iconText`, `imageType`, `size`, `quality`, `dialogWidth`, `dialogHeight`, `imageBoxAttr`, `imageAttr`, `buttonAttr`, `croperAttr`
-- Emit: `update` sau khi upload thành công (`{ returnData, imageData }`)
-- Example:
+- Emit: `update` after successful upload (`{ returnData, imageData }`)
 
 ```json
 {
@@ -222,11 +201,7 @@ Components dùng để nhận input hoặc tương tác với người dùng. Xe
 
 - Props (source): `label`, `url`, `autoclose`, `iconText`, `filters`, `resize`, `onclose`
 - Emit: `input` on upload complete
-- Behavior:
-  - dùng Plupload
-  - tự upload khi chọn file
-  - chạy `onclose` action khi dialog đóng
-- Example:
+- Uses Plupload; uploads on file select; runs `onclose` action when the dialog closes
 
 ```json
 {
@@ -246,71 +221,72 @@ Components dùng để nhận input hoặc tương tác với người dùng. Xe
 
 ## f-excel-reader
 
-Nút upload đọc file Excel/CSV → đẩy dữ liệu đã parse vào `v-model` (mảng object, hoặc mảng lồng mảng tuỳ `:header`). Thư viện XLSX lazy-load khi người dùng chọn file lần đầu, **không cần khai import** trong module.json.
+Button: reads Excel/CSV → `v-model` (array of objects, or of arrays per `:header`). XLSX lazy-loads on first pick; **no import** in module.json.
 
-**Đầu ra:**
-- `v-model` — mảng dữ liệu đã parse
-- `load` — object metadata: `{ rows, rowCount, headers, sheetName, sheetNames, fileName }`
-- `error` — `{ message, fileName }` khi file quá lớn, đọc thất bại, hoặc XLSX load timeout
-- `action-error` — `{ message, fileName }` khi action callback ném lỗi (dữ liệu Excel vẫn hợp lệ)
+**Outputs:**
 
-**Props — Hiển thị:**
+- `v-model` — parsed data array
+- `load` — metadata `{ rows, rowCount, headers, sheetName, sheetNames, fileName }`
+- `error` — `{ message, fileName }` when file too large, read fails, or XLSX load times out
+- `action-error` — `{ message, fileName }` when the action callback throws (Excel data still valid)
 
-| Prop | Default | Mô tả |
-|---|---|---|
-| `label` | `'Load Excel'` | Nhãn nút |
-| `icon-text` | `'mdi-grid'` | Icon Vuetify MDI; `null`/`''` để ẩn icon |
-| `accept` | `.xlsx,.xlsb,.xlsm,.xls,.csv,.txt,.ods,.dbf,.prn,.html,.htm` | Loại file chấp nhận |
+**Props — display:**
 
-**Props — Đọc dữ liệu:**
+| Prop        | Default                                                      | Description                    |
+| ----------- | ------------------------------------------------------------ | ------------------------------ |
+| `label`     | `'Load Excel'`                                               | Button label                   |
+| `icon-text` | `'mdi-grid'`                                                 | MDI icon; `null`/`''` hides it |
+| `accept`    | `.xlsx,.xlsb,.xlsm,.xls,.csv,.txt,.ods,.dbf,.prn,.html,.htm` | Accepted file types            |
 
-| Prop | Default | Mô tả |
-|---|---|---|
-| `:header` | `null` | Quyết định key của mỗi object trong mảng kết quả (xem bảng bên dưới) |
-| `:raw` | `false` | `false` = parse số và ngày; `true` = giữ nguyên raw string |
-| `date-format` | `'dd/mm/yyyy'` | Format ngày khi `:raw="false"` |
-| `:defval` | `''` | Giá trị thay thế cho ô trống |
-| `:sheet` | `0` | Sheet cần đọc — số (index 0-based) hoặc tên sheet (string) |
-| `:skip-rows` | `0` | Bỏ qua N dòng đầu trước khi đọc header/data |
+**Props — reading:**
 
-**Giá trị của `:header`:**
+| Prop          | Default        | Description                                                   |
+| ------------- | -------------- | ------------------------------------------------------------- |
+| `:header`     | `null`         | Decides the object keys in the result (table below)           |
+| `:raw`        | `false`        | `false` = parse numbers and dates; `true` = keep raw strings  |
+| `date-format` | `'dd/mm/yyyy'` | Date format when `:raw="false"`                               |
+| `:defval`     | `''`           | Value for empty cells                                         |
+| `:sheet`      | `0`            | Sheet to read — number (0-based index) or sheet name (string) |
+| `:skip-rows`  | `0`            | Skip N leading rows before header/data                        |
 
-| Giá trị | Kết quả |
-|---|---|
-| `null` _(mặc định)_ | Dùng dòng đầu tiên của sheet làm tên key: `[{MSSV:"1234", HoTen:"An"}]` |
-| `1` | Trả mảng lồng mảng, không có key: `[["MSSV","HoTen"],["1234","An"]]` |
-| `"A"` | Dùng chữ cái cột Excel làm key: `[{A:"MSSV", B:"HoTen"}]` |
-| `["ma","ten"]` | Tự đặt tên key theo thứ tự cột (không dùng dòng header trong file) |
+**`:header` values:**
 
-⚠️ **Bẫy `:sheet` — sai tên thì KHÔNG báo lỗi.** Hai kiểu giá trị hỏng khác hẳn nhau:
+| Value              | Result                                                        |
+| ------------------ | ------------------------------------------------------------- |
+| `null` _(default)_ | First sheet row as keys: `[{MSSV:"1234", HoTen:"An"}]`        |
+| `1`                | Array of arrays, no keys: `[["MSSV","HoTen"],["1234","An"]]`  |
+| `"A"`              | Excel column letters as keys: `[{A:"MSSV", B:"HoTen"}]`       |
+| `["ma","ten"]`     | Your own key names by column order (file header row not used) |
 
-- `:sheet` là **tên** không tồn tại → **im lặng đọc sheet đầu tiên**. Vẫn ra dữ liệu, chỉ là dữ liệu của sheet khác — gõ sai tên sheet không có dấu hiệu nào.
-- `:sheet` là **số** vượt quá số sheet → ném lỗi `Không tìm thấy sheet: N` qua event `error`.
+⚠️ **`:sheet` trap — wrong name does NOT error:**
 
-Dùng tên sheet thì đối chiếu `sheetName` trong event `load` với tên mình mong đợi.
+- Nonexistent **name** → **silently reads the first sheet** (wrong data, no sign).
+- **Number** beyond sheet count → `Không tìm thấy sheet: N` via `error`.
 
-**Props — Giới hạn & timeout:**
+With a name, compare `load`.`sheetName` to the expected name.
 
-| Prop | Default | Mô tả |
-|---|---|---|
-| `:max-size` | `20` | Giới hạn kích thước file, **đơn vị MB** (tên prop không mang chữ "MB"); `0` = bỏ giới hạn |
-| `:load-timeout` | `15000` | Timeout nạp thư viện XLSX (ms) |
+**Props — limits & timeout:**
 
-Giá trị `:max-size` không parse được thành số thì **quay về 20 MB**, không phải bỏ giới hạn — muốn bỏ giới hạn phải truyền đúng số `0`.
+| Prop            | Default | Description                                                   |
+| --------------- | ------- | ------------------------------------------------------------- |
+| `:max-size`     | `20`    | File size limit, **in MB** (name has no "MB"); `0` = no limit |
+| `:load-timeout` | `15000` | XLSX library load timeout (ms)                                |
 
-**Prop — Callback:**
+Unparseable `:max-size` → **20 MB**, not unlimited; no limit = exactly number `0`.
 
-| Prop | Mô tả |
-|---|---|
-| `:action` | Action object chạy sau khi parse xong và `v-model` đã nhận dữ liệu — thường dùng `{ "CALL": "tenAction" }` |
+**Prop — callback:**
 
-**Ranh giới lỗi — đọc Excel và chạy action là hai giai đoạn tách hẳn:**
+| Prop      | Description                                                                                      |
+| --------- | ------------------------------------------------------------------------------------------------ |
+| `:action` | Action object run after parsing, once `v-model` has the data — usually `{ "CALL": "tenAction" }` |
 
-- `action` chỉ chạy sau khi `v-model` đã nhận dữ liệu mới (qua `$nextTick`), nên trong action cứ đọc thẳng `vueData.excelRows`.
-- Một khi Excel đã đọc xong, **không lỗi nào còn biến thành event `error` được nữa** — lỗi của action đi ra `action-error`, và dữ liệu đã parse vẫn nguyên vẹn, không rollback. Nghĩa là nhận được `error` ⇒ chắc chắn hỏng ở khâu đọc file; nhận được `action-error` ⇒ file đọc tốt, hỏng ở xử lý phía sau.
-- Bấm nút lần nữa khi đang parse thì bị bỏ qua; nếu chọn file mới trước khi file cũ parse xong thì kết quả của lượt cũ bị vứt, không ghi đè lượt mới.
+**Error boundary — reading and action are separate stages:**
 
-**Ví dụ cơ bản — header từ dòng đầu (mặc định):**
+- `action` runs after `v-model` has the data (`$nextTick`); read `vueData.excelRows` directly.
+- After reading, **nothing becomes `error`** — action errors → `action-error`, parsed data kept, no rollback. `error` ⇒ reading failed; `action-error` ⇒ processing failed.
+- Clicks while parsing are ignored; a new file picked before the old finishes discards the old result (never overwrites the new).
+
+**Basic — header from first row (default):**
 
 ```json
 {
@@ -325,7 +301,7 @@ Giá trị `:max-size` không parse được thành số thì **quay về 20 MB*
 }
 ```
 
-**Ví dụ — đọc sheet theo tên, bỏ 2 dòng đầu, giữ raw string:**
+**Sheet by name, skip 2 rows, keep raw strings:**
 
 ```json
 {
@@ -342,7 +318,7 @@ Giá trị `:max-size` không parse được thành số thì **quay về 20 MB*
 }
 ```
 
-**Ví dụ — tự đặt tên cột, giới hạn 5 MB:**
+**Custom column names, 5 MB limit:**
 
 ```json
 {