@fui-org/fui-cli 0.2.0 → 0.3.0

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

@@ -0,0 +1,359 @@
+# 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**.
+
+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).
+
+## f-radiobox
+
+- Props (source): `label`, `items`, `itemValue`, `itemText`
+- Emit: `input` on change
+- Example:
+
+```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`
+- 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:
+
+```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
+- Behavior: debounced API search (500ms), bỏ qua keyword < 2 ký tự
+- Example:
+
+```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`
+- Behavior:
+  - debounced click (500ms, leading)
+  - validates form khi `checkvalid=true`
+  - nếu `$attrs.target == 'dialog'`, mở window theo attrs (`wid`, `title`, `url`, `onclose`)
+- Example:
+
+```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 (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:
+
+```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` (hoặc `null`)
+- Behavior: typed mask + time picker
+- Example:
+
+```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`: 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:
+
+```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`
+- Behavior: render QR image từ value
+- Example:
+
+```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` (đóng dialog), `update` (decoded content)
+- Example:
+
+```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` sau khi upload thành công (`{ returnData, imageData }`)
+- Example:
+
+```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
+- Behavior:
+  - dùng Plupload
+  - tự upload khi chọn file
+  - chạy `onclose` action khi dialog đóng
+- Example:
+
+```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
+
+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.
+
+**Đầ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ệ)
+
+**Props — Hiển thị:**
+
+| 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 — Đọc dữ liệu:**
+
+| 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 |
+
+**Giá trị của `:header`:**
+
+| 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) |
+
+⚠️ **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:
+
+- `: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`.
+
+Dùng tên sheet thì đối chiếu `sheetName` trong event `load` với tên mình mong đợi.
+
+**Props — Giới hạn & timeout:**
+
+| 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) |
+
+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 — Callback:**
+
+| 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" }` |
+
+**Ranh giới lỗi — đọc Excel và chạy action là hai giai đoạn tách hẳn:**
+
+- `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.
+
+**Ví dụ cơ bản — header từ dòng đầu (mặc định):**
+
+```json
+{
+  "el": "f-excel-reader",
+  "w": "4",
+  "attr": {
+    "label": "Nhập từ Excel",
+    "icon-text": "mdi-microsoft-excel",
+    ":action": { "CALL": "cmdImportExcel" },
+    "v-model": "excelRows"
+  }
+}
+```
+
+**Ví dụ — đọc sheet theo tên, bỏ 2 dòng đầu, giữ raw string:**
+
+```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"
+  }
+}
+```
+
+**Ví dụ — tự đặt tên cột, giới hạn 5 MB:**
+
+```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"
+  }
+}
+```