@fui-org/fui-cli 1.2.1 → 1.3.2

package/skills/fui-skill-cli/references/components-echart.md

@@ -0,0 +1,316 @@
+# f-echart — ECharts V5 (Core)
+
+> Owns: **`f-echart` core: import, architecture, props, config, theme, DataView, common errors**. Per-chart templates + module.json patterns: [echart-templates.md](echart-templates.md).
+
+Use `f-echart` for all charts: bar, line, pie, scatter, gauge, radar, heatmap, sankey, tree, map, graph...
+
+> ⚠️ `:option`/`:config` most often break **"`:attr` takes a pure expression only"**. Multi-step option building → `script.js` function called via `EXE`; no IIFE / `var` / `return` in JSON (⇒ blank page, 0 JS errors, 0 Vue warnings). See [advanced-techniques.md](advanced-techniques.md) §1.
+
+---
+
+## Import — required, in order
+
+Missing → no component, blank page.
+
+```
+1. /include/chart/echarts.min.js   ← ECharts core (phải đứng TRƯỚC)
+2. /include/chart/fechart.js       ← FUI wrapper (phải đứng SAU)
+```
+
+`fui import list` → `fui import new` → `fui import delete`: [component-quickref.md](component-quickref.md). Sort = load order; `fechart.js` needs global `echarts` → **larger sort** (e.g. 100 / 110).
+
+---
+
+## Architecture — Direct Mode only
+
+Built **entirely on Apache ECharts V5**; `fechart.js` is a thin wrapper (themes, `config` shortcuts, DataView, events). **`option` is plain ECharts option** — use ECharts knowledge; only `config` is FUI-specific. No Auto mode, no `config.type`.
+
+- `option` — **primary**, full ECharts option → `echarts.setOption()`.
+- `config` — FUI shortcuts (height, theme, title, toolbox...); defaults, overridden by `option`.
+
+**Merge:** `config` base, then lodash `_.merge` with `option`: objects deep-merge, primitives replace, **arrays merge by index, NOT replace** ⚠️. `config` produces only `color` (`config.color`) and `dataZoom` (`config.zoom`); with both `config.color` and `option.color` the shorter can't drop the longer's tail:
+
+```js
+config.color = ["#111", "#222", "#333", "#444"];
+option.color = ["#aaa", "#bbb"];
+// → ['#aaa','#bbb','#333','#444']   ← 2 màu cũ còn sót lại
+```
+
+⇒ Palette in **one place** (prefer `config.color`). `series`/`xAxis`/`yAxis`/`grid` never come from `config` — declare freely.
+
+Rendered with `setOption(opt, true)` (**notMerge**): each render replaces the whole option.
+
+---
+
+## DEFAULT conventions (apply unprompted, unless user asks otherwise)
+
+1. **Show values** — bar: `label: { show: true, position: 'top' }` (horizontal → `'right'`); line: `label: { show: true, position: 'top' }`.
+2. **Grid**: axis charts default `left: 0`, `right: 0`, `top: 50`, `bottom: 50` (top/bottom auto-grow for title/legend). Declare only sides the user wants changed; `containLabel: true` if labels may clip.
+3. **Full numbers** (`1,500,000`), no `1.5M`/`1.2k` unless asked; tooltip default `formatFull` is correct — don't override.
+4. **Pie**: no long messy labelLines; short labels (name + % if needed) or rely on legend + tooltip.
+5. **No hand-built "View data" button** — `config.dataView: true`.
+
+---
+
+## Props
+
+Only `config` (Object, `{}`) and `option` (Object, `{}`, primary). **No `data` prop.**
+
+## config keys
+
+| Key                                                | Default         | Notes                                                                                                                                          |
+| -------------------------------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `height`                                           | `400`           | number = px; string e.g. `'50vh'`                                                                                                              |
+| `theme`                                            | `'fui'`         | **Only** `'fui'`\|`'shine'`\|`'v5'`; others (incl. `echarts.registerTheme` names) or `null` **silently → `'fui'`**. Recolor via `config.color` |
+| `backgroundColor`                                  | `'transparent'` |                                                                                                                                                |
+| `title` / `subtitle`                               |                 | → `option.title.text` / `.subtext`                                                                                                             |
+| `titleAlign`                                       | `'center'`      | `'left'`/`'center'`/`'right'` (old alias `titleLeft`)                                                                                          |
+| `titleSize`                                        | `16`            | px                                                                                                                                             |
+| `titleColor`                                       |                 | empty = theme                                                                                                                                  |
+| `titleWeight`                                      | `'bold'`        | `'normal'`/`'bold'`/`500`...                                                                                                                   |
+| `titleFont`                                        |                 | font-family, title + subtitle                                                                                                                  |
+| `titleStyle`                                       |                 | full ECharts textStyle — **wins over all `title*`**                                                                                            |
+| `subtitleSize` / `subtitleColor` / `subtitleStyle` | `12`            | same, subtitle                                                                                                                                 |
+| `color`                                            |                 | palette (string[])                                                                                                                             |
+| `animation`                                        |                 | `false` = off                                                                                                                                  |
+| `animationDuration` / `animationEasing`            |                 | ms / ECharts easing                                                                                                                            |
+| `legend`                                           |                 | `false` hide; `true`/Object show, merged with `{ type:'scroll', left:'center' }`. **No top/bottom** — engine sets it                           |
+| `legendPosition`                                   | `'bottom'`      | `'top'`/`'bottom'`; **only when legend enabled via `config.legend`/`config.legendConfig`**                                                     |
+| `legendRows`                                       | `1`             | rows to reserve; >1 when items wrap. Any legend declaration                                                                                    |
+| `legendConfig`                                     |                 | extra legend props (after `legend`)                                                                                                            |
+| `tooltip`                                          |                 | merged into `{ confine: true }`. **No default `trigger`** → `'item'`; multi-series axis charts need `tooltip: { trigger: 'axis' }` in `option` |
+| `tooltipFormat`                                    | `'auto'`        | `'number'`/`'percent'`/`'currency'`/`'short'`/`'auto'`; `'auto'` = full with separators; `'short'` = `1.5M`, only if asked                     |
+| `decimals`                                         |                 | for `'number'`/`'percent'`/`'currency'`                                                                                                        |
+| `symbol`                                           | `'₫'`           | for `'currency'`                                                                                                                               |
+| `tooltipFormatter`                                 |                 | Function, **wins over `tooltipFormat`**                                                                                                        |
+| `toolbox`                                          | `false`         | saveAsImage + restore                                                                                                                          |
+| `toolboxConfig`                                    |                 | override/extend toolbox                                                                                                                        |
+| `dataView`                                         | `false`         | table button (Vue overlay), data from `option`                                                                                                 |
+| `zoom`                                             |                 | dataZoom inside + slider                                                                                                                       |
+| `zoomConfig`                                       |                 | Array, override dataZoom                                                                                                                       |
+| `refreshInterval`                                  |                 | ms auto-refresh                                                                                                                                |
+
+**Default tooltip needs no config** (centered category title; dot + left label + right value; full numbers `2,535` not `2.5K`). Use `tooltipFormat`/`tooltipFormatter` only for another format.
+
+---
+
+## Grid padding vs `boundaryGap`
+
+- Plot area ↔ canvas edge → `option.grid.top`/`bottom`/`left`/`right`.
+- First/last point/bar ↔ axis ends → `boundaryGap` on that `xAxis`/`yAxis`.
+
+No `padding` prop; `boundaryGap` doesn't replace `grid`. Numbers = px, `'10%'` = percent. Cartesian default:
+
+```js
+grid: { top: 50, bottom: 50, left: 0, right: 0 }
+```
+
+`top`/`bottom` are minimums (engine grows them for title/legend). A side declared in `option.grid` wins and is no longer auto-computed. Only horizontal change → declare only those:
+
+```js
+grid: { left: 12, right: 24, containLabel: true }
+```
+
+Exact values for all four → declare all four; check title/legend don't overlap:
+
+```js
+grid: { top: 40, bottom: 60, left: 12, right: 24, containLabel: true }
+```
+
+`containLabel: true` keeps long/edge axis labels inside. `grid` affects only axis charts; pie, funnel, treemap, sankey, graph ignore it → `series.top`/`bottom`/`left`/`right` (or `center`/`radius`).
+
+No `boundaryGap` set by `fechart.js`; ECharts defaults: `category` → `true`; `value`/`time`/`log` → `[0, 0]`. Line touching both category ends:
+
+```js
+xAxis: { type: 'category', boundaryGap: false, data: labels }
+```
+
+Bars usually keep `true`. Horizontal bar → `yAxis.boundaryGap`. Value/time margins:
+
+```js
+xAxis: { type: 'time', boundaryGap: ['5%', '5%'] }
+```
+
+"Blank space at line ends" → `boundaryGap`; "padding around chart/canvas" → `grid`.
+
+---
+
+## Vertical layout engine
+
+ECharts places title/legend/plot absolutely. After merge, `f-echart` stacks top-down and bottom-up: each present block takes **its height + a gap**; remainder = plot.
+
+| Constant               | px                                        |
+| ---------------------- | ----------------------------------------- |
+| padding to canvas edge | 8                                         |
+| min gap between blocks | 12                                        |
+| grid left / right      | 0 / 0 (overridable)                       |
+| grid top / bottom min  | 50 / 50                                   |
+| title height           | `round(fontSize × 1.4)` (16px → 22)       |
+| subtitle height        | `4 + round(fontSize × 1.4)` (12px → 4+17) |
+| legend row             | 24 × `legendRows`                         |
+| x-axis label reserve   | +26 to `grid.bottom`                      |
+| y-axis label reserve   | +10 to `grid.top`                         |
+
+Axis charts get the remainder as `grid.top`/`grid.bottom`; **pie / funnel / treemap / sankey / graph** as `series.top`/`series.bottom`, except a series with px `center` (left untouched).
+
+Measured (axis chart, default title):
+
+| Config                           | `title.top` | `legend`    | `grid.top` | `grid.bottom` |
+| -------------------------------- | ----------- | ----------- | ---------- | ------------- |
+| no title, no legend              | —           | —           | 50         | 50            |
+| title only                       | 8           | —           | 52         | 50            |
+| title + `config.legend: true`    | 8           | `bottom: 8` | 52         | 70            |
+| title + `legendPosition:'top'`   | 8           | `top: 42`   | 88         | 50            |
+| as above + `legendRows: 2`       | 8           | `top: 42`   | 112        | 50            |
+| title `titleSize: 24` + subtitle | 8           | —           | 85         | 50            |
+
+**Legend edge, first match wins:**
+
+1. `legend.top` set → top; `legend.bottom` set → bottom (value kept).
+2. Enabled via `config.legend`/`config.legendConfig` → `config.legendPosition` (default **`'bottom'`**).
+3. Only in `option.legend` → **top**; ⚠️ `config.legendPosition` ignored — use `option.legend.bottom: 0` or `config.legend: true`.
+
+Don't tweak `grid.top`/`grid.bottom`/`legend.top` to dodge a title — space is re-added. **Module-declared values are always kept** (`grid.top: 5` stays; later blocks stack from it) → declare only for a custom layout. Wrapping legend → `legendRows`.
+
+Limits: only **px numbers** are computed (`'10%'`/`'middle'` keep just a minimum); array `option.grid` (multi-grid) is ignored — module handles layout.
+
+---
+
+## DataView
+
+`config.dataView: true` → table icon top-right → overlay table. Data from `option.dataset.source` (object-array or array-of-arrays), else `option.series[].data` + `xAxis.data`/`yAxis.data`; none → button hidden.
+
+```json
+{
+  "el": "f-echart",
+  "w": "12",
+  "attr": {
+    ":config": "{ title: 'Doanh thu', dataView: true, height: 350 }",
+    ":option": "vueData.chartOpt"
+  }
+}
+```
+
+Custom **Vue overlay**, **not** ECharts toolbox DataView (`config.toolbox: true` = saveAsImage + restore only). Omit without a clear series array (single-value gauge, sankey node/link, hierarchical tree...).
+
+---
+
+## Series auto-enhancement (theme policy)
+
+| Policy      | Applies to                 | Effect                                                                                      |
+| ----------- | -------------------------- | ------------------------------------------------------------------------------------------- |
+| `lighten`   | `bar`, `pie`, `funnel`     | 50% lighter fill + original-color border; bar per-series, pie/funnel per-item palette color |
+| `separator` | `treemap`, `sunburst`      | faint white border between cells/layers                                                     |
+| `outline`   | `scatter`, `effectScatter` | white outline around points                                                                 |
+
+Disable: bar → `itemStyle.color` in `option.series[]`; pie item → `itemStyle.color` on each `data[]` item; separator/outline → `itemStyle.borderWidth: 0` in `option.series[]`.
+
+---
+
+## Theme
+
+Built in: `'fui'` (56 colors, **default**), `'shine'` (8, classic axis, strong colors), `'v5'` (9, ECharts V5 default).
+
+```json
+":config": "{ theme: 'shine' }"
+":config": "{ theme: 'v5' }"
+```
+
+⚠️ **Only these three.** Other names (incl. `echarts.registerTheme('myTheme', …)`) and `null` **silently → `'fui'`**, no error. Recolor with `config.color` (also read by auto-enhancement):
+
+```json
+":config": "{ color: ['#e63946', '#457b9d', '#2a9d8f'] }"
+```
+
+---
+
+## Events & methods
+
+Events: `chart-click` (params) · `drilldown` (alias) · `legend-change` (params) · `rendered` (after each `setOption`) · `finished` (animation done).
+
+```json
+{ "v-on:drilldown": "CALL(vueData.loadDetail, { row: $event })" }
+```
+
+```js
+this.$refs.myChart.getInstance(); // ECharts instance gốc
+this.$refs.myChart.refresh(); // Force re-render (gọi lại setOption)
+this.$refs.myChart.exportImage("chart.png");
+this.$refs.myChart.resizeChart(); // Hiếm khi cần — xem ghi chú dưới
+```
+
+`resizeChart()` rarely needed: listens to `window.resize` **and** a `ResizeObserver` on its container (Vuetify grid settle, tab/dialog open, sidebar collapse).
+
+```js
+// Native ECharts API
+const chart = vueData.$refs.myChart.getInstance();
+chart.dispatchAction({ type: "highlight", seriesIndex: 0, dataIndex: 2 });
+chart.on("mouseover", (p) => {
+  vueData.hoverLabel = p.name;
+});
+```
+
+---
+
+## FEchartFormatter (global, script.js) — exactly 6 functions
+
+```js
+FEchartFormatter.build("currency", { symbol: "₫", decimals: 0 })(1500000); // → '₫1,500,000'
+FEchartFormatter.formatShort(1500000); // → '1.5M' (co gọn — chỉ dùng khi cần tiết kiệm chỗ, vd axis label)
+FEchartFormatter.formatNumber(1500000); // → '1,500,000'  (decimals thứ 2, mặc định 0)
+FEchartFormatter.formatFull(2535.678); // → '2,535.68' (đầy đủ, tối đa 2 số thập phân — mặc định của tooltip)
+// Tạo tooltip formatter từ config.tooltipFormat ('auto'/không khai → formatFull, số đầy đủ)
+FEchartFormatter.buildTooltip({ tooltipFormat: "currency", symbol: "₫" });
+FEchartFormatter.buildDefault(); // formatter tooltip mặc định (formatFull)
+```
+
+- **No** `formatPercent`/`formatCurrency` → `build('percent', { decimals })` / `build('currency', { symbol, decimals })`.
+- Bare `FEchartFormatter` only; `window.FEchartFormatter` is `undefined` (script-level `const`).
+
+---
+
+## Sorting
+
+No `config.sort`; sort in `script.js` before assigning. Never ECharts `dataset.transform sort` on object-arrays (unstable in V5).
+
+```js
+vueData.rows = (d.data || []).slice().sort((a, b) => b.doanhThu - a.doanhThu);
+// String sort
+vueData.rows = (d.data || []).slice().sort((a, b) => a.name.localeCompare(b.name));
+```
+
+---
+
+## module.json pattern
+
+```json
+{
+  "el": "f-echart",
+  "w": "12",
+  "attr": {
+    ":config": "{ title: 'Tiêu đề', height: 350, dataView: true }",
+    ":option": "vueData.chartOpt"
+  }
+}
+```
+
+Build `vueData.chartOpt` in `script.js` (fetch callback). Per-type templates + 5 patterns (inline, vueData ref, dynamic height, conditional option, no-dataview): [echart-templates.md](echart-templates.md).
+
+---
+
+## Common errors
+
+| Symptom                                          | Cause                                                                          | Fix                                                                 |
+| ------------------------------------------------ | ------------------------------------------------------------------------------ | ------------------------------------------------------------------- |
+| Blank page / no component                        | `fechart.js` not imported                                                      | `fui import list` → add                                             |
+| `echarts is not defined`                         | `fechart.js` sort < `echarts.min.js`                                           | swap sorts                                                          |
+| Empty chart with data                            | data outside `option` (no `data` prop)                                         | `option.series`                                                     |
+| No DataView button                               | nothing extractable from `option`                                              | add series/axis data                                                |
+| Pale bar fill                                    | lighten (50%)                                                                  | `itemStyle.color` in `option.series[]`                              |
+| No update on filter change                       | `config`/`option` are **deep-watched** ⇒ variable **not declared in `data[]`** | declare in module.json `data[]`; at worst `$refs.myChart.refresh()` |
+| `config.type` ignored                            | doesn't exist                                                                  | `option.series[].type`                                              |
+| Custom theme ignored                             | silently `'fui'`                                                               | `config.color`                                                      |
+| Stray colors                                     | palette in both `config.color` and `option.color`                              | one place                                                           |
+| Legend on top despite `legendPosition: 'bottom'` | legend in `option`, not `config.legend`                                        | `option.legend.bottom: 0` or `config.legend: true`                  |
+| Tooltip shows 1 series                           | no default `trigger`                                                           | `tooltip: { trigger: 'axis' }` in `option`                          |
+| Multi-row legend overlaps                        | engine reserves **1 row**                                                      | `config.legendRows: 2`+                                             |

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

@@ -0,0 +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"
+  }
+}
+```