@fui-org/fui-cli 1.3.2 → 2.0.0

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

@@ -1,230 +1,189 @@
-# f-echart — Biểu đồ ECharts V5 (Core)
+# f-echart — ECharts V5 (Core)
 
-> File này sở hữu: **`f-echart` core: import, kiến trúc, props, config, theme, DataView, lỗi thường gặp**. Template từng loại chart xem [echart-templates.md](echart-templates.md).
+> Owns: **`f-echart` core: import, architecture, props, config, theme, DataView, common errors**. Per-chart templates + module.json patterns: [echart-templates.md](echart-templates.md).
 
-Dùng `f-echart` cho mọi loại biểu đồ: bar, line, pie, scatter, gauge, radar, heatmap, sankey, tree, map, graph...
+Use `f-echart` for all charts: bar, line, pie, scatter, gauge, radar, heatmap, sankey, tree, map, graph...
 
-> ⚠️ `:option` / `:config` của `f-echart` là nơi luật **"`:attr` chỉ nhận expression thuần"** hay bị vi phạm nhất — logic dựng option nhiều bước phải nằm trong hàm `script.js` gọi qua `EXE`, không nhét IIFE / `var` / `return` vào JSON (vi phạm ⇒ trang trắng, 0 JS error, 0 Vue warn). Luật đầy đủ: [advanced-techniques.md](advanced-techniques.md) §1.
-
-File này là **core**: import, kiến trúc, props, config, theme, DataView, events, lỗi thường gặp. **Template từng loại chart + các pattern module.json** đã tách sang [echart-templates.md](echart-templates.md) — load thêm khi đã biết cần vẽ loại chart nào.
+> ⚠️ `: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 — Bắt buộc, đúng thứ tự
+## Import — required, in order
 
-`f-echart` yêu cầu 2 file JS nền tảng. Không có → component không tồn tại, trang trắng.
+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)
 ```
 
-Quy trình `file_import_list` → `file_import_new` → `file_import_delete`: xem
-[component-quickref.md](component-quickref.md). **Điểm đặc thù của f-echart** — sort number quyết
-định thứ tự load, và `fechart.js` phụ thuộc biến `echarts` global nên **PHẢI có sort lớn hơn**
-`echarts.min.js` (ví dụ `echarts.min.js` = 100, `fechart.js` = 110).
+`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).
 
 ---
 
-## Kiến trúc — Direct Mode
-
-`f-echart` **xây dựng hoàn toàn trên Apache ECharts V5** (echarts.apache.org). `fechart.js` chỉ là lớp bọc mỏng: nạp theme, vài shortcut trong `config`, DataView, events. **Mọi thứ trong `option` chính là ECharts option** — khi cần cấu hình chart, **dùng thẳng kiến thức Apache ECharts** (option, series, axis, visualMap, dataZoom...); chỉ `config` là shortcut riêng của FUI.
+## Architecture — Direct Mode only
 
-`f-echart` là **Direct Mode only**. Bạn viết ECharts `option` trực tiếp — không có Auto mode, không có `config.type`.
+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`.
 
-| Prop | Vai trò |
-|---|---|
-| `option` | **Primary** — full ECharts option, truyền thẳng vào `echarts.setOption()`. Dùng kiến thức Apache ECharts |
-| `config` | Meta/shortcut riêng FUI: height, theme, title, toolbox... Là defaults, bị `option` merge đè |
+- `option` — **primary**, full ECharts option → `echarts.setOption()`.
+- `config` — FUI shortcuts (height, theme, title, toolbox...); defaults, overridden by `option`.
 
-**Thứ tự merge:** `config` xây base → `option` merge đè lên bằng `_.merge` (lodash).
-- Plain objects → **deep-merge**
-- Primitives → **replace**
-- Arrays → **merge theo chỉ số**, KHÔNG phải replace ⚠️
-
-Bẫy của merge-theo-chỉ-số: `config` chỉ sinh ra hai mảng là `color` (từ `config.color`) và `dataZoom` (từ `config.zoom`). Nếu cả `config.color` lẫn `option.color` cùng có, mảng ngắn hơn **không xoá được đuôi của mảng dài hơn**:
+**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'];
+config.color = ["#111", "#222", "#333", "#444"];
+option.color = ["#aaa", "#bbb"];
 // → ['#aaa','#bbb','#333','#444']   ← 2 màu cũ còn sót lại
 ```
 
-⇒ Chọn **một chỗ duy nhất** để khai palette (khuyến nghị `config.color`), đừng khai cả hai. Với `series`/`xAxis`/`yAxis`/`grid` thì `config` không bao giờ sinh ra nên không có va chạm — cứ khai thoải mái trong `option`.
+⇒ Palette in **one place** (prefer `config.color`). `series`/`xAxis`/`yAxis`/`grid` never come from `config` — declare freely.
 
-Sau khi merge, chart luôn được vẽ bằng `setOption(opt, true)` (**notMerge**) — mỗi lần render là thay toàn bộ option, không sót cấu hình của lần trước.
+Rendered with `setOption(opt, true)` (**notMerge**): each render replaces the whole option.
 
 ---
 
-## Quy ước hiển thị MẶC ĐỊNH (làm đúng ngay từ đầu, không chờ user nhắc)
-
-Đúc kết từ các yêu cầu chỉnh sửa lặp lại nhiều lần của user thật. Áp dụng mặc định cho mọi chart mới/refactor — chỉ bỏ qua khi user yêu cầu rõ kiểu khác:
+## DEFAULT conventions (apply unprompted, unless user asks otherwise)
 
-1. **Luôn hiển thị giá trị trên chart** — bar: `label: { show: true, position: 'top' }` (horizontal bar → `position: 'right'`); line: `label: { show: true, position: 'top' }`.
-2. **Grid padding**: mặc định chart có hệ trục dùng `left: 0`, `right: 0`, `top: 50`, `bottom: 50`; `top`/`bottom` tự tăng nếu title/legend cần thêm chỗ. Chỉ khai cạnh mà user yêu cầu đổi; thêm `containLabel: true` khi nhãn trục có nguy cơ bị cắt. Xem "Grid padding và boundaryGap".
-3. **Số hiển thị đầy đủ** có phân cách nghìn (`1,500,000`) — không rút gọn `1.5M`/`1.2k` trừ khi user yêu cầu (mặc định `formatFull` của tooltip đã đúng — đừng override).
-4. **Pie**: không để labelLine ("râu") dài rối; label ngắn gọn (tên + % nếu cần) hoặc dồn thông tin về legend + tooltip.
-5. **Không tự dựng nút "Xem dữ liệu"** — dùng `config.dataView: true` có sẵn của f-echart.
+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
 
-| Prop | Type | Default | Mô tả |
-|---|---|---|---|
-| `config` | Object | `{}` | Shortcut settings |
-| `option` | Object | `{}` | Full ECharts option — primary |
+Only `config` (Object, `{}`) and `option` (Object, `{}`, primary). **No `data` prop.**
 
-> Component chỉ có 2 props: `config` và `option`. **Không có `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.
 
 ---
 
-## config keys
+## 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:
 
-| Key | Type | Default | Mô tả |
-|---|---|---|---|
-| `height` | number\|string | `400` | Số = `px`; string = `'50vh'`... |
-| `theme` | string | `'fui'` | **Chỉ nhận** `'fui'`\|`'shine'`\|`'v5'`. Tên khác (kể cả theme tự `echarts.registerTheme`) và `null` đều **âm thầm rơi về `'fui'`** — đổi màu thì dùng `config.color` |
-| `backgroundColor` | string | `'transparent'` | Override background |
-| `title` | string | | → `option.title.text` |
-| `subtitle` | string | | → `option.title.subtext` |
-| `titleAlign` | string | `'center'` | `'left'`/`'center'`/`'right'` (bí danh cũ: `titleLeft`) |
-| `titleSize` | number | `16` | Cỡ chữ title (px) |
-| `titleColor` | string | | Màu chữ title — bỏ trống thì theo theme |
-| `titleWeight` | string\|number | `'bold'` | `'normal'`/`'bold'`/`500`... |
-| `titleFont` | string | | font-family cho cả title lẫn subtitle |
-| `titleStyle` | Object | | ECharts textStyle đầy đủ — **thắng mọi key `title*` ở trên** |
-| `subtitleSize` / `subtitleColor` / `subtitleStyle` | | `12` | Tương tự, cho subtitle |
-| `color` | string[] | | Override color palette |
-| `animation` | boolean | | `false` = tắt animation |
-| `animationDuration` | number | | ms |
-| `animationEasing` | string | | ECharts easing name |
-| `legend` | true\|false\|Object | | `false` = ẩn; `true`/Object = bật, merge với `{ type:'scroll', left:'center' }` — **không đặt top/bottom**, vị trí dọc do layout engine tính |
-| `legendPosition` | string | `'bottom'` | Cạnh legend neo vào: `'top'`/`'bottom'`. **Chỉ có tác dụng khi legend được bật qua `config.legend`/`config.legendConfig`** — xem "Khoảng trống & bố cục dọc" |
-| `legendRows` | number | `1` | Số hàng legend cần chừa chỗ — đặt >1 khi nhiều mục xuống dòng. Có tác dụng với mọi cách khai legend |
-| `legendConfig` | Object | | Extra legend props (merge sau `legend`) |
-| `tooltip` | Object | | Merge vào default `{ confine: true }`. **Không có `trigger` mặc định** → ECharts dùng `'item'`; chart nhiều series theo trục phải tự khai `tooltip: { trigger: 'axis' }` trong `option` |
-| `tooltipFormat` | string | `'auto'` | `'number'`/`'percent'`/`'currency'`/`'short'`/`'auto'`. `'auto'` = số đầy đủ có phân cách nghìn (`1,500,000`); `'short'` = co gọn (`1.5M`) — chỉ dùng khi user yêu cầu rõ |
-| `decimals` | number | | Số chữ số thập phân cho `tooltipFormat` `'number'`/`'percent'`/`'currency'` |
-| `symbol` | string | `'₫'` | Ký hiệu tiền tệ cho `tooltipFormat: 'currency'` |
-| `tooltipFormatter` | Function | | Custom tooltip fn — **thắng `tooltipFormat`** |
-| `toolbox` | boolean | `false` | Hiện toolbox (saveAsImage + restore) |
-| `toolboxConfig` | Object | | Override/extend toolbox features |
-| `dataView` | boolean | `false` | Hiện nút bảng (Vue overlay) — tự trích xuất data từ `option` |
-| `zoom` | boolean | | dataZoom inside + slider |
-| `zoomConfig` | Array | | Override dataZoom config |
-| `refreshInterval` | number | | ms — auto-refresh |
-
-**Tooltip mặc định đã đẹp sẵn — KHÔNG cần cấu hình gì thêm:** title (tên category) canh giữa, mỗi dòng series gồm chấm màu + label canh trái, giá trị canh phải, số hiển thị đầy đủ có phân cách nghìn (`2,535` chứ không phải `2.5K`). Chỉ đụng vào `tooltipFormat`/`tooltipFormatter` khi user yêu cầu format khác (`percent`, `currency`, co gọn `short`...).
+```js
+xAxis: { type: 'time', boundaryGap: ['5%', '5%'] }
+```
+
+"Blank space at line ends" → `boundaryGap`; "padding around chart/canvas" → `grid`.
 
 ---
 
-## Grid padding và `boundaryGap` — chọn đúng cấu hình
-
-Hai khái niệm này giải quyết hai loại khoảng trống khác nhau:
-
-| User muốn thay đổi | Cấu hình đúng | Vị trí khai |
-|---|---|---|
-| Khoảng cách từ vùng vẽ tới mép canvas | `grid.top` / `grid.bottom` / `grid.left` / `grid.right` | `option.grid` |
-| Khoảng hở từ điểm/cột đầu và cuối tới hai đầu trục | `boundaryGap` | ngay trong `xAxis` hoặc `yAxis` tương ứng |
-
-`f-echart` không có prop `padding`, và `boundaryGap` không thay thế cho `grid`. Số trong `grid` là px; chuỗi như `'10%'` dùng phần trăm. Mặc định wrapper cho chart Cartesian là:
-
-```js
-grid: { top: 50, bottom: 50, left: 0, right: 0 }
-```
-
-`top`/`bottom` là mức tối thiểu: layout engine có thể tăng để tránh title/legend. Mỗi cạnh user khai trong `option.grid` sẽ thắng mặc định và không còn được engine tự tính. Vì vậy, nếu user chỉ yêu cầu đổi padding ngang, chỉ khai hai cạnh ngang:
-
-```js
-grid: { left: 12, right: 24, containLabel: true }
-```
-
-Nếu user yêu cầu con số chính xác cho cả bốn cạnh, khai đủ bốn cạnh; cần kiểm tra title/legend không đè vùng vẽ:
-
-```js
-grid: { top: 40, bottom: 60, left: 12, right: 24, containLabel: true }
-```
-
-`containLabel: true` giúp giữ nhãn trục trong vùng `grid`; dùng khi nhãn dài hoặc sát mép. `grid` chỉ điều khiển chart Cartesian có `xAxis`/`yAxis`. Pie, funnel, treemap, sankey và graph bỏ qua `grid`; chỉnh khoảng trống của chúng bằng `series.top` / `bottom` / `left` / `right` (hoặc `center` / `radius` theo loại chart).
-
-`fechart.js` không đặt `boundaryGap`, nên giữ mặc định ECharts:
-
-- Trục `category`: `boundaryGap: true`.
-- Trục `value`, `time`, `log`: `boundaryGap: [0, 0]`.
-
-Khi user muốn line chart chạm hai đầu trục category, đặt `boundaryGap: false` trên chính trục category:
-
-```js
-xAxis: { type: 'category', boundaryGap: false, data: labels }
-```
-
-Bar chart thường giữ `boundaryGap: true` để cột đầu/cuối không bị ép sát mép. Với horizontal bar, trục category là `yAxis`, nên đặt ở `yAxis.boundaryGap`. Với trục `value`/`time`, có thể chừa biên theo hai phía:
-
-```js
-xAxis: { type: 'time', boundaryGap: ['5%', '5%'] }
-```
-
-Khi user nói "bỏ khoảng trắng hai đầu đường dữ liệu", ưu tiên kiểm tra `boundaryGap`; khi user nói "giảm padding quanh biểu đồ/canvas", chỉnh `grid`.
-
----
-
-## Khoảng trống & bố cục dọc (layout box model)
-
-ECharts đặt title / legend / vùng vẽ bằng toạ độ tuyệt đối — nó **không** biết "khối này nằm dưới khối kia". `f-echart` bù lại bằng một layout engine chạy sau khi merge `config` + `option`: đi từ mép trên xuống và từ mép dưới lên, mỗi khối hiện diện lấy **đúng chiều cao của mình + một khoảng hở**, phần chưa ai lấy là vùng vẽ.
-
-| Hằng số | px | Dùng cho |
-|---|---|---|
-| padding | 8 | khoảng hở với mép canvas |
-| gap | 12 | khoảng hở tối thiểu giữa hai khối bất kỳ |
-| grid trái / phải | 0 / 0 | mặc định vùng vẽ Cartesian; module có thể override từng cạnh |
-| grid trên / dưới | 50 / 50 | mức tối thiểu khi module không khai; title/legend có thể làm tăng |
-| chiều cao title | `round(fontSize × 1.4)` | mặc định `16px` → 22 |
-| chiều cao subtitle | `4 + round(fontSize × 1.4)` | mặc định `12px` → 4+17 |
-| một hàng legend | 24 | nhân với `legendRows` |
-| chừa nhãn trục hoành | 26 | cộng thêm vào `grid.bottom` |
-| chừa nhãn trục tung | 10 | cộng thêm vào `grid.top` |
-
-Vùng vẽ nhận phần còn lại qua **hai cơ chế khác nhau**:
-- chart **có hệ trục** (`xAxis`/`yAxis`) → `grid.top` / `grid.bottom`
-- **pie / funnel / treemap / sankey / graph** → `series.top` / `series.bottom`, vì các loại này **bỏ qua `grid` hoàn toàn**. Ngoại lệ: series khai `center` bằng px thì engine không đụng vào (đổi box sẽ dịch hình đi).
-
-Số thực tế (đo trên chính `fechart.js`), chart có trục, title mặc định:
-
-| Cấu hình | `title.top` | `legend` | `grid.top` | `grid.bottom` |
-|---|---|---|---|---|
-| không title, không legend | — | — | 50 | 50 |
-| chỉ title | 8 | — | 52 | 50 |
-| title + `config.legend: true` | 8 | `bottom: 8` | 52 | 70 |
-| title + `legendPosition:'top'` | 8 | `top: 42` | 88 | 50 |
-| như trên + `legendRows: 2` | 8 | `top: 42` | 112 | 50 |
-| title `titleSize: 24` + subtitle | 8 | — | 85 | 50 |
-
-### Legend neo cạnh nào — luật quyết định
-
-Đọc theo thứ tự, dừng ở điều kiện đầu tiên đúng:
-
-1. `legend.top` có giá trị → neo **trên**; `legend.bottom` có giá trị → neo **dưới** (giá trị module khai được giữ nguyên).
-2. Legend bật qua `config.legend` / `config.legendConfig` → `config.legendPosition`, mặc định **`'bottom'`**.
-3. Legend chỉ khai trong `option.legend` (không qua `config`) → neo **trên**. ⚠️ Trong ca này `config.legendPosition` **không có tác dụng** — muốn legend xuống đáy thì hoặc đặt `option.legend.bottom: 0`, hoặc bật legend qua `config.legend: true`.
-
-**Hệ quả khi viết module:** đừng tự chỉnh `grid.top`/`grid.bottom`/`legend.top` để "né" title — thêm title, đổi `titleSize`, hay chuyển `legendPosition` thì khoảng trống tự cộng lại. Giá trị **do module tự khai luôn được tôn trọng** (khai `grid.top: 5` thì engine không đụng vào, và khối sau vẫn cộng dồn từ giá trị đó), nên chỉ khai khi thật sự cần một bố cục riêng. Legend nhiều mục xuống dòng thì báo `legendRows` thay vì tự đẩy `grid.top`.
-
-Hai giới hạn đã biết: (a) engine chỉ tính được `top`/`bottom` dạng **số px** — khai `'10%'`/`'middle'` thì nó chỉ giữ một mức tối thiểu, phần còn lại tự canh; (b) `option.grid` dạng **mảng** (multi-grid) thì engine bỏ qua hoàn toàn, module tự lo bố cục.
+## 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` → hiện icon bảng (góc trên phải chart). Click → overlay bảng dữ liệu phủ lên chart.
-
-**DataView tự trích xuất từ `option` — không cần truyền data riêng:**
-- Ưu tiên `option.dataset.source` (object-array hoặc array-of-arrays)
-- Fallback: `option.series[].data` + `xAxis.data` / `yAxis.data`
-- Không có data phù hợp → nút bảng ẩn tự động
+`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",
+  "el": "f-echart",
+  "w": "12",
   "attr": {
     ":config": "{ title: 'Doanh thu', dataView: true, height: 350 }",
     ":option": "vueData.chartOpt"
@@ -232,51 +191,32 @@ Hai giới hạn đã biết: (a) engine chỉ tính được `top`/`bottom` d
 }
 ```
 
-> DataView là **Vue overlay tùy chỉnh** — **không phải** ECharts toolbox DataView. `config.toolbox: true` chỉ thêm saveAsImage + restore.
-
-Bỏ `dataView` khi option không có series array rõ ràng (gauge giá trị đơn, sankey node/link, tree hierarchical...).
+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
-
-`f-echart` tự động áp style theo loại series — điều khiển bởi **enhancement policy** của theme:
+## Series auto-enhancement (theme policy)
 
-| Policy | Áp cho | Hành vi |
-|---|---|---|
-| `lighten` | `bar`, `pie`, `funnel` | Fill màu nhạt 50% + viền màu gốc |
-| `separator` | `treemap`, `sunburst` | Viền trắng mờ giữa các ô/lớp |
-| `outline` | `scatter`, `effectScatter` | Viền trắng quanh điểm |
+| 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                                                                 |
 
-**`lighten` detail:**
-- `bar` — per-series: một màu nhạt + viền cho toàn bộ cột
-- `pie` / `funnel` — per-item: mỗi lát/phần tử lấy màu riêng từ palette rồi làm nhạt
-
-**Override:**
-- Tắt lighten cho bar: đặt `itemStyle.color` tường minh trong `option.series[]`
-- Tắt lighten cho pie item: đặt `itemStyle.color` vào từng phần tử `data[]`
-- Tắt separator/outline: đặt `itemStyle.borderWidth: 0` trong `option.series[]`
+Disable: bar → `itemStyle.color` in `option.series[]`; pie item → `itemStyle.color` on each `data[]` item; separator/outline → `itemStyle.borderWidth: 0` in `option.series[]`.
 
 ---
 
 ## Theme
 
-3 theme nhúng sẵn trong `fechart.js` — không cần file ngoài:
-
-| Theme | Màu | Đặc điểm |
-|---|---|---|
-| `'fui'` | 56 màu | **Mặc định** — palette rộng, nhiều series |
-| `'shine'` | 8 màu | Classic axis style, màu đậm nét |
-| `'v5'` | 9 màu | ECharts V5 default style |
+Built in: `'fui'` (56 colors, **default**), `'shine'` (8, classic axis, strong colors), `'v5'` (9, ECharts V5 default).
 
 ```json
 ":config": "{ theme: 'shine' }"
 ":config": "{ theme: 'v5' }"
 ```
 
-> ⚠️ **Chỉ ba tên trên là hợp lệ.** Mọi tên khác — kể cả theme tự đăng ký bằng `echarts.registerTheme('myTheme', …)` — và cả `theme: null` đều **âm thầm rơi về `'fui'`**, không lỗi, không cảnh báo. Đừng dùng `config.theme` cho theme custom.
-
-**Đổi bảng màu thì dùng `config.color`** — đây là đường được hỗ trợ, và cũng là bảng màu mà series auto-enhancement đọc để tính màu fill/viền:
+⚠️ **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'] }"
@@ -284,65 +224,54 @@ Bỏ `dataView` khi option không có series array rõ ràng (gauge giá trị
 
 ---
 
-## Events
+## Events & methods
 
-| Event | Payload | Mô tả |
-|---|---|---|
-| `chart-click` | params | Click data point |
-| `drilldown` | params | Alias của `chart-click` |
-| `legend-change` | params | Chọn/bỏ legend item |
-| `rendered` | — | Sau mỗi lần `setOption` |
-| `finished` | — | Sau khi animation xong |
+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 })" }
 ```
 
----
-
-## Exposed methods (`$refs`)
-
 ```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
+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
 ```
 
-> **Không cần gọi `resizeChart()` thủ công trong hầu hết trường hợp**: component đã tự nghe `window.resize` **và** `ResizeObserver` trên chính thẻ chứa chart, nên chart co giãn đúng cả khi container đổi kích thước mà viewport không đổi (Vuetify grid settle sau mount, mở tab/dialog, thu gọn sidebar).
+`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; });
+chart.dispatchAction({ type: "highlight", seriesIndex: 0, dataIndex: 2 });
+chart.on("mouseover", (p) => {
+  vueData.hoverLabel = p.name;
+});
 ```
 
 ---
 
-## FEchartFormatter (global, dùng trong script.js)
-
-Đúng 6 hàm, không có gì khác:
+## 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)
+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)
+FEchartFormatter.buildTooltip({ tooltipFormat: "currency", symbol: "₫" });
+FEchartFormatter.buildDefault(); // formatter tooltip mặc định (formatFull)
 ```
 
-Hai điểm dễ sai:
-- **Không có** `formatPercent` / `formatCurrency` rời — muốn hai kiểu đó thì đi qua `build('percent', { decimals })` / `build('currency', { symbol, decimals })`.
-- Truy cập bằng **tên trần** `FEchartFormatter`, **không phải** `window.FEchartFormatter` (khai bằng `const` ở cấp script nên không gắn lên `window`; `window.FEchartFormatter` là `undefined`).
+- **No** `formatPercent`/`formatCurrency` → `build('percent', { decimals })` / `build('currency', { symbol, decimals })`.
+- Bare `FEchartFormatter` only; `window.FEchartFormatter` is `undefined` (script-level `const`).
 
 ---
 
-## Sort dữ liệu
+## Sorting
 
-Không có `config.sort`. Sort trong `script.js` trước khi gán:
+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);
@@ -350,11 +279,9 @@ vueData.rows = (d.data || []).slice().sort((a, b) => b.doanhThu - a.doanhThu);
 vueData.rows = (d.data || []).slice().sort((a, b) => a.name.localeCompare(b.name));
 ```
 
-> **Không dùng ECharts `dataset.transform sort`** với object-array — không ổn định với ECharts V5.
-
 ---
 
-## Pattern trong module.json (controls)
+## module.json pattern
 
 ```json
 {
@@ -367,25 +294,23 @@ vueData.rows = (d.data || []).slice().sort((a, b) => a.name.localeCompare(b.name
 }
 ```
 
-`vueData.chartOpt` được build trong `script.js` (callback sau khi fetch data). `dataView: true` tự trích xuất dữ liệu từ `option` để hiển thị bảng.
-
-> **Template từng loại chart (bar/line/pie/gauge/radar/heatmap/sankey/tree/graph...) + 5 pattern module.json (inline, vueData ref, dynamic height, conditional option, no-dataview):** xem [echart-templates.md](echart-templates.md).
+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).
 
 ---
 
-## Lỗi thường gặp
-
-| Lỗi | Nguyên nhân | Giải pháp |
-|---|---|---|
-| Trang trắng / component không tồn tại | Thiếu `fechart.js` trong import | `file_import_list` → thêm nếu thiếu |
-| `echarts is not defined` | `fechart.js` sort nhỏ hơn `echarts.min.js` | Đảo sort: `echarts.min.js` phải có số nhỏ hơn |
-| Chart trống dù data có | Data nằm ngoài `option` (ví dụ cố truyền qua prop `data` không tồn tại) | Data chart phải trong `option.series` — không có prop `data` |
-| Nút DataView không hiện | `option` không có series array hoặc axis data | DataView chỉ hiện khi tự trích được data từ `option` |
-| Bar fill nhạt | Auto lighten enhancement (50%) | Set `itemStyle.color` tường minh trong `option.series[]` |
-| Chart không update khi filter thay đổi | `config`/`option` đều có **deep watch** nên sửa lồng sâu vẫn vẽ lại — không update nghĩa là biến **chưa khai trong `data[]`** (Vue không theo dõi được) | Khai key trong `data[]` module.json rồi mới gán; cùng lắm gọi `$refs.myChart.refresh()` |
-| `config.type` không có tác dụng | f-echart không có config.type | Đặt `type` trong `option.series[].type` |
-| Theme custom không ăn | `config.theme` chỉ nhận `'fui'`/`'shine'`/`'v5'`, tên khác **âm thầm** về `'fui'` | Đổi màu bằng `config.color` |
-| Palette lạ, có màu không khai ở đâu | Khai màu ở **cả** `config.color` lẫn `option.color` → merge theo chỉ số, đuôi mảng dài hơn còn sót | Chỉ khai palette ở một chỗ |
-| Legend nằm trên đầu dù đặt `legendPosition: 'bottom'` | Legend khai trong `option` (không qua `config.legend`) thì neo **trên**, `legendPosition` vô hiệu | `option.legend.bottom: 0`, hoặc bật legend bằng `config.legend: true` |
-| Tooltip chỉ hiện 1 series khi rê chuột | Không có `trigger` mặc định → ECharts dùng `'item'` | Khai `tooltip: { trigger: 'axis' }` trong `option` |
-| Legend nhiều hàng đè lên chart | Engine mặc định chừa chỗ cho **1 hàng** legend | `config.legendRows: 2` (hoặc hơn) |
+## 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`+                                             |