@fui-org/fui-cli 2.1.3 → 2.2.0

package/skills/{fui-skill → fui}/references/components-input.md

@@ -1,335 +1,335 @@
-# FUI Input & Interaction Components
-
-> Owns: **input components: `f-date`, `f-time`, `f-search`, `f-radiobox`, `f-button`, `f-menu`, upload**.
-
-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
-
-```json
-{
-  "el": "f-radiobox",
-  "w": "6",
-  "attr": {
-    "label": "Loai",
-    "v-model": "formData.loai",
-    ":items": "loaiOptions",
-    "item-value": "value",
-    "item-text": "text"
-  }
-}
-```
-
-## f-menu
-
-- Props (source): `items`, `label`, `iconText`, `menuAttr`
-- 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
-{
-  "el": "f-menu",
-  "w": "3",
-  "attr": {
-    "label": "Tac vu",
-    "icon-text": "mdi-dots-vertical",
-    ":items": [
-      { "text": "Xem chi tiết", "icon-text": "mdi-eye", "action": { "CALL": "vueData.viewDetail" } },
-      { "text": "Xuất Excel", "icon-text": "mdi-file-excel", "action": { "CALL": "vueData.exportExcel" } },
-      { "text": "Trang chủ", "icon-text": "mdi-home", "href": "/", "target": "_blank" }
-    ]
-  }
-}
-```
-
-## f-search
-
-- Props (source): `api`, `apiData`, `items`
-- Emit: `input` when selection changes
-- Debounced API search (500ms); keywords < 2 chars ignored
-
-```json
-{
-  "el": "f-search",
-  "w": "6",
-  "attr": {
-    "v-model": "filter.userID",
-    "api": "/api/user/search",
-    ":api-data": { "Keyword": "TEXT", "GroupID": "vueData.groupID" },
-    "item-text": "UserName",
-    "item-value": "UserID"
-  }
-}
-```
-
-## f-button
-
-- Props (source): `label`, `checkvalid`, `ctrlhotkey`, `iconText`, `action`, `includeData`
-- Debounced click (500ms, leading); validates form when `checkvalid=true`
-- `$attrs.target == 'dialog'` → opens a window from attrs (`wid`, `title`, `url`, `onclose`)
-
-```json
-{
-  "el": "f-button",
-  "w": "3",
-  "attr": {
-    "label": "Luu",
-    "color": "primary",
-    ":action": { "CALL": "handleSubmit" }
-  }
-}
-```
-
-## f-date
-
-- Props (source): `value`, `label`, `dateAdd`, `required`
-- Emit: `input` with normalized date (or `null`)
-- Typed mask + picker; accepts many input formats on init; `dateAdd` sets a date relative to today
-
-```json
-{
-  "el": "f-date",
-  "w": "6",
-  "attr": {
-    "v-model": "filter.fromDate",
-    "label": "Tu ngay",
-    ":required": false,
-    ":date-add": -7
-  }
-}
-```
-
-## f-time
-
-- Props (source): `value`, `label`, `timeAdd`, `required`
-- Emit: `input` with `HH:mm` (or `null`)
-- Typed mask + time picker
-
-```json
-{
-  "el": "f-time",
-  "w": "6",
-  "attr": {
-    "v-model": "formData.startTime",
-    "label": "Gio bat dau",
-    ":required": false,
-    ":time-add": 30
-  }
-}
-```
-
-## f-time-counter
-
-- Props (source): `value`, `type`, `labelFormat`, `format`
-- `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
-{
-  "el": "f-time-counter",
-  "w": "4",
-  "attr": {
-    ":value": 300,
-    ":type": 0,
-    ":format": { "label": "Còn lại: ", "day": " ngày", "hour": " giờ", "minute": " phút", "second": " giây" }
-  }
-}
-```
-
-## f-qrcode
-
-- Props (source): `value`, `logo`, `color`, `size`
-- Renders a QR image from value
-
-```json
-{
-  "el": "f-qrcode",
-  "w": "4",
-  "attr": {
-    "v-model": "formData.qrText",
-    ":size": 200,
-    "color": "#1e90ff"
-  }
-}
-```
-
-## f-qrcode-reader
-
-- Props (source): `value`, `label`, `width`
-- Emit: `input` (closes dialog), `update` (decoded content)
-
-```json
-{
-  "el": "f-qrcode-reader",
-  "w": "12",
-  "attr": {
-    "v-model": "scanDialog",
-    "label": "Doc ma QR",
-    "v-on:update": "CALL(vueData.handleScanResult, { item: $event })"
-  }
-}
-```
-
-## f-image-update
-
-- Props (source): `value`, `label`, `title`, `apiUpload`, `iconText`, `imageType`, `size`, `quality`, `dialogWidth`, `dialogHeight`, `imageBoxAttr`, `imageAttr`, `buttonAttr`, `croperAttr`
-- Emit: `update` after successful upload (`{ returnData, imageData }`)
-
-```json
-{
-  "el": "f-image-update",
-  "w": "4",
-  "attr": {
-    "v-model": "formData.avatar",
-    "label": "Anh dai dien",
-    "api-upload": "/api/upload/avatar",
-    ":dialog-width": 600,
-    ":dialog-height": 420
-  }
-}
-```
-
-## f-file-upload
-
-- Props (source): `label`, `url`, `autoclose`, `iconText`, `filters`, `resize`, `onclose`
-- Emit: `input` on upload complete
-- Uses Plupload; uploads on file select; runs `onclose` action when the dialog closes
-
-```json
-{
-  "el": "f-file-upload",
-  "w": "4",
-  "attr": {
-    "label": "Tai tep",
-    "url": "/api/upload/file",
-    ":filters": {
-      "max_file_size": "20mb",
-      "mime_types": [{ "title": "PDF", "extensions": "pdf" }]
-    },
-    ":onclose": { "CALL": "handleUploadClosed" }
-  }
-}
-```
-
-## f-excel-reader
-
-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.
-
-**Outputs:**
-
-- `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)
-
-**Props — display:**
-
-| 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            |
-
-**Props — reading:**
-
-| 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                        |
-
-**`:header` values:**
-
-| 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` trap — wrong name does NOT error:**
-
-- 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`.
-
-With a name, compare `load`.`sheetName` to the expected name.
-
-**Props — limits & timeout:**
-
-| 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)                                |
-
-Unparseable `:max-size` → **20 MB**, not unlimited; no limit = exactly number `0`.
-
-**Prop — callback:**
-
-| Prop      | Description                                                                                      |
-| --------- | ------------------------------------------------------------------------------------------------ |
-| `:action` | Action object run after parsing, once `v-model` has the data — usually `{ "CALL": "tenAction" }` |
-
-**Error boundary — reading and action are separate stages:**
-
-- `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
-{
-  "el": "f-excel-reader",
-  "w": "4",
-  "attr": {
-    "label": "Nhập từ Excel",
-    "icon-text": "mdi-microsoft-excel",
-    ":action": { "CALL": "cmdImportExcel" },
-    "v-model": "excelRows"
-  }
-}
-```
-
-**Sheet by name, skip 2 rows, keep raw strings:**
-
-```json
-{
-  "el": "f-excel-reader",
-  "w": "4",
-  "attr": {
-    "label": "Nhập DanhSach",
-    ":sheet": "DanhSach",
-    ":skip-rows": 2,
-    ":raw": true,
-    ":action": { "CALL": "cmdImportExcel" },
-    "v-model": "excelRows"
-  }
-}
-```
-
-**Custom column names, 5 MB limit:**
-
-```json
-{
-  "el": "f-excel-reader",
-  "w": "4",
-  "attr": {
-    "label": "Nhập Excel",
-    ":header": ["mssv", "hoTen", "diemTB"],
-    ":max-size": 5,
-    ":action": { "CALL": "cmdImportExcel" },
-    "v-model": "excelRows"
-  }
-}
-```
+# FUI Input & Interaction Components
+
+> Owns: **input components: `f-date`, `f-time`, `f-search`, `f-radiobox`, `f-button`, `f-menu`, upload**.
+
+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
+
+```json
+{
+  "el": "f-radiobox",
+  "w": "6",
+  "attr": {
+    "label": "Loai",
+    "v-model": "formData.loai",
+    ":items": "loaiOptions",
+    "item-value": "value",
+    "item-text": "text"
+  }
+}
+```
+
+## f-menu
+
+- Props (source): `items`, `label`, `iconText`, `menuAttr`
+- 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
+{
+  "el": "f-menu",
+  "w": "3",
+  "attr": {
+    "label": "Tac vu",
+    "icon-text": "mdi-dots-vertical",
+    ":items": [
+      { "text": "Xem chi tiết", "icon-text": "mdi-eye", "action": { "CALL": "vueData.viewDetail" } },
+      { "text": "Xuất Excel", "icon-text": "mdi-file-excel", "action": { "CALL": "vueData.exportExcel" } },
+      { "text": "Trang chủ", "icon-text": "mdi-home", "href": "/", "target": "_blank" }
+    ]
+  }
+}
+```
+
+## f-search
+
+- Props (source): `api`, `apiData`, `items`
+- Emit: `input` when selection changes
+- Debounced API search (500ms); keywords < 2 chars ignored
+
+```json
+{
+  "el": "f-search",
+  "w": "6",
+  "attr": {
+    "v-model": "filter.userID",
+    "api": "/api/user/search",
+    ":api-data": { "Keyword": "TEXT", "GroupID": "vueData.groupID" },
+    "item-text": "UserName",
+    "item-value": "UserID"
+  }
+}
+```
+
+## f-button
+
+- Props (source): `label`, `checkvalid`, `ctrlhotkey`, `iconText`, `action`, `includeData`
+- Debounced click (500ms, leading); validates form when `checkvalid=true`
+- `$attrs.target == 'dialog'` → opens a window from attrs (`wid`, `title`, `url`, `onclose`)
+
+```json
+{
+  "el": "f-button",
+  "w": "3",
+  "attr": {
+    "label": "Luu",
+    "color": "primary",
+    ":action": { "CALL": "handleSubmit" }
+  }
+}
+```
+
+## f-date
+
+- Props (source): `value`, `label`, `dateAdd`, `required`
+- Emit: `input` with normalized date (or `null`)
+- Typed mask + picker; accepts many input formats on init; `dateAdd` sets a date relative to today
+
+```json
+{
+  "el": "f-date",
+  "w": "6",
+  "attr": {
+    "v-model": "filter.fromDate",
+    "label": "Tu ngay",
+    ":required": false,
+    ":date-add": -7
+  }
+}
+```
+
+## f-time
+
+- Props (source): `value`, `label`, `timeAdd`, `required`
+- Emit: `input` with `HH:mm` (or `null`)
+- Typed mask + time picker
+
+```json
+{
+  "el": "f-time",
+  "w": "6",
+  "attr": {
+    "v-model": "formData.startTime",
+    "label": "Gio bat dau",
+    ":required": false,
+    ":time-add": 30
+  }
+}
+```
+
+## f-time-counter
+
+- Props (source): `value`, `type`, `labelFormat`, `format`
+- `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
+{
+  "el": "f-time-counter",
+  "w": "4",
+  "attr": {
+    ":value": 300,
+    ":type": 0,
+    ":format": { "label": "Còn lại: ", "day": " ngày", "hour": " giờ", "minute": " phút", "second": " giây" }
+  }
+}
+```
+
+## f-qrcode
+
+- Props (source): `value`, `logo`, `color`, `size`
+- Renders a QR image from value
+
+```json
+{
+  "el": "f-qrcode",
+  "w": "4",
+  "attr": {
+    "v-model": "formData.qrText",
+    ":size": 200,
+    "color": "#1e90ff"
+  }
+}
+```
+
+## f-qrcode-reader
+
+- Props (source): `value`, `label`, `width`
+- Emit: `input` (closes dialog), `update` (decoded content)
+
+```json
+{
+  "el": "f-qrcode-reader",
+  "w": "12",
+  "attr": {
+    "v-model": "scanDialog",
+    "label": "Doc ma QR",
+    "v-on:update": "CALL(vueData.handleScanResult, { item: $event })"
+  }
+}
+```
+
+## f-image-update
+
+- Props (source): `value`, `label`, `title`, `apiUpload`, `iconText`, `imageType`, `size`, `quality`, `dialogWidth`, `dialogHeight`, `imageBoxAttr`, `imageAttr`, `buttonAttr`, `croperAttr`
+- Emit: `update` after successful upload (`{ returnData, imageData }`)
+
+```json
+{
+  "el": "f-image-update",
+  "w": "4",
+  "attr": {
+    "v-model": "formData.avatar",
+    "label": "Anh dai dien",
+    "api-upload": "/api/upload/avatar",
+    ":dialog-width": 600,
+    ":dialog-height": 420
+  }
+}
+```
+
+## f-file-upload
+
+- Props (source): `label`, `url`, `autoclose`, `iconText`, `filters`, `resize`, `onclose`
+- Emit: `input` on upload complete
+- Uses Plupload; uploads on file select; runs `onclose` action when the dialog closes
+
+```json
+{
+  "el": "f-file-upload",
+  "w": "4",
+  "attr": {
+    "label": "Tai tep",
+    "url": "/api/upload/file",
+    ":filters": {
+      "max_file_size": "20mb",
+      "mime_types": [{ "title": "PDF", "extensions": "pdf" }]
+    },
+    ":onclose": { "CALL": "handleUploadClosed" }
+  }
+}
+```
+
+## f-excel-reader
+
+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.
+
+**Outputs:**
+
+- `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)
+
+**Props — display:**
+
+| 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            |
+
+**Props — reading:**
+
+| 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                        |
+
+**`:header` values:**
+
+| 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` trap — wrong name does NOT error:**
+
+- 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`.
+
+With a name, compare `load`.`sheetName` to the expected name.
+
+**Props — limits & timeout:**
+
+| 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)                                |
+
+Unparseable `:max-size` → **20 MB**, not unlimited; no limit = exactly number `0`.
+
+**Prop — callback:**
+
+| Prop      | Description                                                                                      |
+| --------- | ------------------------------------------------------------------------------------------------ |
+| `:action` | Action object run after parsing, once `v-model` has the data — usually `{ "CALL": "tenAction" }` |
+
+**Error boundary — reading and action are separate stages:**
+
+- `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
+{
+  "el": "f-excel-reader",
+  "w": "4",
+  "attr": {
+    "label": "Nhập từ Excel",
+    "icon-text": "mdi-microsoft-excel",
+    ":action": { "CALL": "cmdImportExcel" },
+    "v-model": "excelRows"
+  }
+}
+```
+
+**Sheet by name, skip 2 rows, keep raw strings:**
+
+```json
+{
+  "el": "f-excel-reader",
+  "w": "4",
+  "attr": {
+    "label": "Nhập DanhSach",
+    ":sheet": "DanhSach",
+    ":skip-rows": 2,
+    ":raw": true,
+    ":action": { "CALL": "cmdImportExcel" },
+    "v-model": "excelRows"
+  }
+}
+```
+
+**Custom column names, 5 MB limit:**
+
+```json
+{
+  "el": "f-excel-reader",
+  "w": "4",
+  "attr": {
+    "label": "Nhập Excel",
+    ":header": ["mssv", "hoTen", "diemTB"],
+    ":max-size": 5,
+    ":action": { "CALL": "cmdImportExcel" },
+    "v-model": "excelRows"
+  }
+}
+```