@fui-org/fui-cli 2.1.3 → 2.2.0

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

@@ -1,316 +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`+                                             |
+# 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 one expression only"**: a `;` (even at the end) or a leading `var`/`return` in JSON ⇒ blank page. Multi-step option building → `script.js` function called via `EXE`. 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`+                                             |