@fui-org/fui-cli 2.1.4 → 2.2.0

package/skills/{fui-skill → fui}/references/advanced-techniques.md

@@ -1,168 +1,170 @@
-# Advanced FUI Techniques
-
-> Owns: **advanced techniques: `EXE`, `MAP`, complex expressions, pure-expression rule for `:attr`, rule that functions called in `EXE`/`FUN` must really exist**. Basic action engine: [controls-patterns.md](controls-patterns.md).
-
----
-
-## 1. `:attr` takes a PURE EXPRESSION — never statements
-
-**Hard rule.** Every binding value in `module.json` — `:option`, `:config`, `:items`, `:headers`, `:style`, every `v-bind:*` — goes **straight to Vue's template compiler**, which accepts **one expression**. Never include:
-
-- `function(){ ... }` or IIFE `(function(){...})()`
-- `return`
-- `var` / `let` / `const`
-- `;` joining statements
-
-### Why it is worse than it looks
-
-A statement in `:attr` breaks template compilation and Vue **swallows the error**: **blank page, 0 JS errors, 0 `[Vue warn]`**, no stack trace — found only after many `fui module simulate --render` rounds. That is why `fui module validate` reports it as an **error**, not a warning.
-
-> Unlike `data[]` / `IN` / `{{ }}`, which go through FUI's `getVueData()` (see [controls-patterns.md](controls-patterns.md) §0 Value Resolution) with their own rules, `:attr` does **not**.
-
-### Allowed in `:attr`
-
-| Form                               | Example                                                 |
-| ---------------------------------- | ------------------------------------------------------- |
-| Object / array literal             | `":config": "{ height: 300, legend: { show: true } }"`  |
-| Ternary                            | `":color": "ok ? 'primary' : 'warning'"`                |
-| Arrow `.map` / `.filter` chains    | `":items": "ds.filter(x => x.Active).map(x => x.Name)"` |
-| Property access / vueData variable | `":option": "optThe"`                                   |
-
-### Complex logic → `script.js` + `EXE`
-
-Multi-step transforms, temp variables, loops, complex conditions → **not in `:attr`**:
-
-1. Write a plain function in `script.js`: `function tenHam(){ ... }`
-2. It **assigns directly to `vueData.xxx`** (does not `return` a value for JSON)
-3. Call it via `EXE` — usually in the data-loading action's `CALLBACK`: `"EXE": "tenHam()"`
-4. `:attr` in `module.json` only points at the variable: `":option": "optThe"`
-
-❌ **Wrong** — IIFE in `:attr`:
-
-```json
-":option": "(function(){ var src = vueData.ds.filter(r => r.id===1); return { series:[{data: src}] }; })();"
-```
-
-✅ **Right**:
-
-```javascript
-// script.js
-function buildChart() {
-  var src = vueData.ds.filter(function (r) {
-    return r.id === 1;
-  });
-  vueData.optThe = { series: [{ data: src }] };
-}
-```
-
-```json
-// module.json — action nạp dữ liệu
-"CALLBACK": { "EXE": "buildChart()" },
-// module.json — control
-":option": "optThe"
-```
-
-Declare `:option`'s variable as `{}` in `data[]` so the first render doesn't break; `buildChart()` assigns the real value after the API returns.
-
-### Diagnosing a blank page with "0 JS error, 0 Vue warn"
-
-Not a runtime error — suspect **`:attr` template compilation** first, not `script.js` or the action engine.
-
-Isolate: replace a suspect expression with a simple static value (`":option": "{}"` or remove the attr) and re-render. **Page comes back ⇒ that expression is the culprit.** Repeat per suspect `:attr` until one remains.
-
-Running `fui module validate` before rendering catches most of these as errors.
-
----
-
-## 2. Functions called in `EXE` / `FUN` must REALLY EXIST
-
-**Hard rule.** `"EXE": "buildChart()"` and `"FUN": "buildChart"` work only if `buildChart` is a **real global function** at runtime — declared in `{moduleDir}/script.js`, in an imported `.js` file, or a platform built-in ([default-function.md](default-function.md), [script-map.md](script-map.md)).
-
-This is the flip side of §1: moving logic to `script.js` and calling via `EXE` **often loses its second half**. `module.json` is edited, `EXE` written, `fui module publish json` run — but nobody writes `script.js` or runs `fui module publish script`.
-
-### Why nothing tells you
-
-Two commands, two failure modes, **neither shows the function name prominently**:
-
-| Command | Mechanism                                                                                                                                                                                               | Symptom when missing                                                                                                                  |
-| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
-| `EXE`   | Runs through `templateCompiled(\`<% … %>\`)`— lodash`_.template`. A comma-operator bug at `fastproject-3.0.js:490` means **the data object is never passed**, so bare identifiers resolve to **global** | `ReferenceError: buildChart is not defined` — shows only in `fui module simulate --render`, as just **"1 JS error"** in a long report |
-| `FUN`   | `runFunction()` looks up `window[obj.FUN]`; if absent, `console.log("Func:", …, "not found")` and **continues**                                                                                         | **Completely silent.** No error, no `[Vue warn]`, the action "finishes" and does nothing                                              |
-
-Measured cost: one module burned **36 consecutive `--render` runs over 5 days** on this bug class (`buildKPI8Columns is not defined`).
-
-### The only layer that catches it: **`fui module simulate --render`**
-
-`fui module validate` does **NOT** check this: it does not read `script.js`. (A static rule once did, and was removed — to avoid false positives it had to know **every** platform global, a list never complete; each missing name blocked publishing a working module.) `fui module simulate` in vm mode doesn't catch it either — it doesn't load `script.js` into the sandbox, so it reports ReferenceError for **every** module using `script.js` functions, even correct ones.
-
-So verify with **`--render`**: the real browser throws `ReferenceError: buildChart is not defined`, and **every JS error now makes the result an error (`isError`)** — not only init errors; errors from button clicks count too. The message is in the `═══ CHẨN ĐOÁN ═══` block at the **top** of the report, line `[MODULE]`.
-
-⚠️ **`--render` does not catch the `FUN` case** — `runFunction` just `console.log`s and continues, throwing nothing. For `FUN`, **check function names against `script.js` yourself**; the only symptom is "action finishes, nothing happens".
-
-### Fix
-
-1. Write the function in `script.js`: `function buildChart(){ … vueData.optThe = …; }`
-2. **`fui module publish script`** — the most-forgotten step. `fui module publish json` does **not** push `script.js`.
-3. Typo → fix the name; never add an empty function to silence the error.
-
----
-
-## 3. Advanced Logic & Scripting
-
-JSON logic is limited; use `script.js` for complex operations.
-
-### Computed properties workaround
-
-`module.json` has no native computed properties. Define calculation functions in `script.js` and call them from `module.json`.
-
-**script.js**:
-
-```javascript
-function getTongTien() {
-  return vueData.items.reduce((sum, item) => sum + (item.amount || 0), 0);
-}
-```
-
-**module.json**:
-
-```json
-{
-  "innerHTML": "Total: {{getTongTien().toLocaleString()}} VNĐ"
-}
-```
-
-### Complex validation
-
-Don't write long logic strings in JSON; move validation to `script.js`.
-
-**script.js**:
-
-```javascript
-function validateStep1() {
-  const d = vueData;
-  if (!d.name || !d.email) {
-    alert("Missing required fields!");
-    return false;
-  }
-  return true;
-}
-
-function nextStep() {
-  if (vueData.step === 1 && !validateStep1()) return;
-  vueData.step++;
-}
-```
-
-**module.json**:
-
-```json
-"v-on:click": "nextStep()"
-```
-
-### Action binding
-
-For simple UI logic you may bind JS functions to events directly instead of the `CALL` action protocol.
-
-```json
-"v-on:click": "prevBuoc()"
-```
+# Advanced FUI Techniques
+
+> Owns: **advanced techniques: `EXE`, `MAP`, complex expressions, pure-expression rule for `:attr`, rule that functions called in `EXE`/`FUN` must really exist**. Basic action engine: [controls-patterns.md](controls-patterns.md).
+
+---
+
+## 1. `:attr` takes ONE EXPRESSION — never statements
+
+**Hard rule.** Every binding value in `module.json` — `:option`, `:config`, `:items`, `:headers`, `:style`, every `v-bind:*` — goes **straight to Vue's template compiler**, which compiles it as `return (<value>)`: it must be **one JavaScript expression**. These break it:
+
+- a `;` outside a string, **including one at the end**: `"(function(){ … })();"`
+- a statement at the top: `var` / `let` / `const x = …; x`, a bare `return …`, `if (…) …`
+
+A function **inside** the expression is fine, and was checked on the V3 runtime: `ds.map(function (d) { return d.url })`, a callback prop `":on-close": "() => { vueData.show = false }"`, even an IIFE `(function(){ var a = …; return a })()` without the trailing `;`.
+
+### Why it is worse than it looks
+
+A binding that is not one expression breaks template compilation: **blank page**. At best a console line names the compile error; the agent sees an empty screenshot and starts suspecting everything else. That is why `fui module validate` reports it as an **error** (it checks whether the value parses as one expression), not a warning.
+
+> Unlike `data[]` / `IN` / `{{ }}`, which go through FUI's `getVueData()` (see [controls-patterns.md](controls-patterns.md) §0 Value Resolution) with their own rules, `:attr` does **not**.
+
+### Allowed in `:attr`
+
+| Form                               | Example                                                 |
+| ---------------------------------- | ------------------------------------------------------- |
+| Object / array literal             | `":config": "{ height: 300, legend: { show: true } }"`  |
+| Ternary                            | `":color": "ok ? 'primary' : 'warning'"`                |
+| Arrow `.map` / `.filter` chains    | `":items": "ds.filter(x => x.Active).map(x => x.Name)"` |
+| Property access / vueData variable | `":option": "optThe"`                                   |
+| Function inside the expression     | `":items": "ds.map(function (d) { return d.url })"`     |
+| Callback prop                      | `":on-close": "() => { vueData.show = false }"`         |
+
+### Complex logic → `script.js` + `EXE`
+
+Multi-step transforms, temp variables, loops, complex conditions → **not in `:attr`**. A long IIFE parses, but it is hard to read, cannot be tested on its own, and one stray `;` blanks the page:
+
+1. Write a plain function in `script.js`: `function tenHam(){ ... }`
+2. It **assigns directly to `vueData.xxx`** (does not `return` a value for JSON)
+3. Call it via `EXE` — usually in the data-loading action's `CALLBACK`: `"EXE": "tenHam()"`
+4. `:attr` in `module.json` only points at the variable: `":option": "optThe"`
+
+❌ **Wrong** — the trailing `;` blanks the page, and the logic belongs in `script.js` anyway:
+
+```json
+":option": "(function(){ var src = vueData.ds.filter(r => r.id===1); return { series:[{data: src}] }; })();"
+```
+
+✅ **Right**:
+
+```javascript
+// script.js
+function buildChart() {
+  var src = vueData.ds.filter(function (r) {
+    return r.id === 1;
+  });
+  vueData.optThe = { series: [{ data: src }] };
+}
+```
+
+```json
+// module.json — action nạp dữ liệu
+"CALLBACK": { "EXE": "buildChart()" },
+// module.json — control
+":option": "optThe"
+```
+
+Declare `:option`'s variable as `{}` in `data[]` so the first render doesn't break; `buildChart()` assigns the real value after the API returns.
+
+### Diagnosing a blank page
+
+Not a runtime error — suspect **`:attr` template compilation** first, not `script.js` or the action engine.
+
+Isolate: replace a suspect expression with a simple static value (`":option": "{}"` or remove the attr) and re-render. **Page comes back ⇒ that expression is the culprit.** Repeat per suspect `:attr` until one remains.
+
+Running `fui module validate` before rendering catches these as errors: it reports every binding that does not parse as one expression.
+
+---
+
+## 2. Functions called in `EXE` / `FUN` must REALLY EXIST
+
+**Hard rule.** `"EXE": "buildChart()"` and `"FUN": "buildChart"` work only if `buildChart` is a **real global function** at runtime — declared in `{moduleDir}/script.js`, in an imported `.js` file, or a platform built-in ([default-function.md](default-function.md), [script-map.md](script-map.md)).
+
+This is the flip side of §1: moving logic to `script.js` and calling via `EXE` **often loses its second half**. `module.json` is edited, `EXE` written, `fui module publish json` run — but nobody writes `script.js` or runs `fui module publish script`.
+
+### Why nothing tells you
+
+Two commands, two failure modes, **neither shows the function name prominently**:
+
+| Command | Mechanism                                                                                                                                                                                               | Symptom when missing                                                                                                                  |
+| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `EXE`   | Runs through `templateCompiled(\`<% … %>\`)`— lodash`_.template`. A comma-operator bug at `fastproject-3.0.js:490` means **the data object is never passed**, so bare identifiers resolve to **global** | `ReferenceError: buildChart is not defined` — shows only in `fui module simulate --render`, as just **"1 JS error"** in a long report |
+| `FUN`   | `runFunction()` looks up `window[obj.FUN]`; if absent, `console.log("Func:", …, "not found")` and **continues**                                                                                         | **Completely silent.** No error, no `[Vue warn]`, the action "finishes" and does nothing                                              |
+
+Measured cost: one module burned **36 consecutive `--render` runs over 5 days** on this bug class (`buildKPI8Columns is not defined`).
+
+### The only layer that catches it: **`fui module simulate --render`**
+
+`fui module validate` does **NOT** check this: it does not read `script.js`. (A static rule once did, and was removed — to avoid false positives it had to know **every** platform global, a list never complete; each missing name blocked publishing a working module.) `fui module simulate` in vm mode doesn't catch it either — it doesn't load `script.js` into the sandbox, so it reports ReferenceError for **every** module using `script.js` functions, even correct ones.
+
+So verify with **`--render`**: the real browser throws `ReferenceError: buildChart is not defined`, and **every JS error makes the command fail (exit 1)** — not only init errors; errors from button clicks count too. The message is in the `═══ DIAGNOSIS ═══` block at the **top** of the report, line `[MODULE]`.
+
+⚠️ **`--render` does not catch the `FUN` case** — `runFunction` just `console.log`s and continues, throwing nothing. For `FUN`, **check function names against `script.js` yourself**; the only symptom is "action finishes, nothing happens".
+
+### Fix
+
+1. Write the function in `script.js`: `function buildChart(){ … vueData.optThe = …; }`
+2. **`fui module publish script`** — the most-forgotten step. `fui module publish json` does **not** push `script.js`.
+3. Typo → fix the name; never add an empty function to silence the error.
+
+---
+
+## 3. Advanced Logic & Scripting
+
+JSON logic is limited; use `script.js` for complex operations.
+
+### Computed properties workaround
+
+`module.json` has no native computed properties. Define calculation functions in `script.js` and call them from `module.json`.
+
+**script.js**:
+
+```javascript
+function getTongTien() {
+  return vueData.items.reduce((sum, item) => sum + (item.amount || 0), 0);
+}
+```
+
+**module.json**:
+
+```json
+{
+  "innerHTML": "Total: {{getTongTien().toLocaleString()}} VNĐ"
+}
+```
+
+### Complex validation
+
+Don't write long logic strings in JSON; move validation to `script.js`.
+
+**script.js**:
+
+```javascript
+function validateStep1() {
+  const d = vueData;
+  if (!d.name || !d.email) {
+    alert("Missing required fields!");
+    return false;
+  }
+  return true;
+}
+
+function nextStep() {
+  if (vueData.step === 1 && !validateStep1()) return;
+  vueData.step++;
+}
+```
+
+**module.json**:
+
+```json
+"v-on:click": "nextStep()"
+```
+
+### Action binding
+
+For simple UI logic you may bind JS functions to events directly instead of the `CALL` action protocol.
+
+```json
+"v-on:click": "prevBuoc()"
+```

package/skills/{fui-skill → fui}/references/component-design.md

@@ -427,10 +427,10 @@ fui component preview uc-invoice-list -p <pid> --cases '[
 
 - **Props**: arrays/objects as **real values** (pushed into `data[]`, bound `:prop`). Strings → static attrs; keys starting `:`/`v-` kept verbatim (use `v-on:`/`v-slot:`, **not** `@`/`#`).
 - **`cases × devices` ≤ 8** (each render = real browser session).
-- Also accepted: `slot` (`innerHTML` content), `vueData`, mocks, `user` (test permission gates), `viewport` (force low height to expose self-measuring components). Flags: `fui component preview --help`.
+- Also accepted: `slot` (`innerHTML` content), `vueData`, `apiMocks` (the same map as `--mocks`), `user` (test permission gates), `viewport` (force low height to expose self-measuring components). Flags: `fui component preview --help`.
 - `scenario` uses **the exact `--render` grammar on the real DOM**: `set`/`click`/`call`/`exe`/`assert`; pick rows with `nth` (no `item`/`index`).
 - **Module `style.css` NOT loaded** — component must stand on its own `<style>` + project theme.
-- Returns: screenshots (max 4 inline, rest as paths) + JS errors + `[Vue warn]` + DOM audit. **Read the images and fix** before pushing.
+- Prints, per case × device: a `screenshot:` path (nothing is attached) + JS errors + `[Vue warn]` + DOM audit. **Open and read the images, failed runs first, and fix** before pushing.
 
 ### Project components: MUST push before rendering a module that uses them
 

package/skills/{fui-skill → fui}/references/component-quickref.md

@@ -1,78 +1,78 @@
-# FUI Component Quick Reference
-
-> Owns: **FUI component catalog, components needing JS/CSS imports, add/remove import workflow**. Per-component details: file in the right column.
-
-Prefer `f-*`; use `v-*` only when no FUI equivalent exists.
-
-| Component         | Use for                                                                                                                                                         | Reference                                                                                 |
-| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
-| `f-table`         | **Any datatable** — CRUD via dialog form or view-only (readonly = omit `:update-api`); auto-builds headers when `:headers` omitted; totals row via `sum-format` | [component-table.md](component-table.md)                                                  |
-| `f-dialog`        | Modal with form, watch, buttons                                                                                                                                 | [components-dialog.md](components-dialog.md)                                              |
-| `f-window`        | Dialog opening a URL in an iframe                                                                                                                               | [components-dialog.md](components-dialog.md)                                              |
-| `f-button`        | Button with action, hotkey, form validation                                                                                                                     | [components-input.md](components-input.md)                                                |
-| `f-date`          | Date input with picker + typed mask                                                                                                                             | [components-input.md](components-input.md)                                                |
-| `f-time`          | Time input with picker + typed mask                                                                                                                             | [components-input.md](components-input.md)                                                |
-| `f-time-counter`  | Countdown / clock                                                                                                                                               | [components-input.md](components-input.md)                                                |
-| `f-search`        | API-backed autocomplete                                                                                                                                         | [components-input.md](components-input.md)                                                |
-| `f-menu`          | Dropdown button menu with icon/action/link                                                                                                                      | [components-input.md](components-input.md)                                                |
-| `f-radiobox`      | Radio group from items array                                                                                                                                    | [components-input.md](components-input.md)                                                |
-| `f-file-upload`   | File upload (Plupload, progress dialog)                                                                                                                         | [components-input.md](components-input.md)                                                |
-| `f-image-update`  | Image upload + crop                                                                                                                                             | [components-input.md](components-input.md)                                                |
-| `f-excel-reader`  | Excel/CSV → JSON (pick sheet, skip first N rows, name columns)                                                                                                  | [components-input.md](components-input.md)                                                |
-| `f-qrcode`        | Render QR code                                                                                                                                                  | [components-input.md](components-input.md)                                                |
-| `f-qrcode-reader` | Read QR via camera                                                                                                                                              | [components-input.md](components-input.md)                                                |
-| `f-editor`        | Rich text editor (CKEditor 5)                                                                                                                                   | [components-dialog.md](components-dialog.md)                                              |
-| `f-editor-dialog` | Rich text editor in a modal                                                                                                                                     | [components-dialog.md](components-dialog.md)                                              |
-| `f-echart`        | **Charts** — ECharts V5: bar, line, pie, scatter, gauge, radar, heatmap, sankey, tree, map, graph...                                                            | [components-echart.md](components-echart.md) · [echart-templates.md](echart-templates.md) |
-| `f-sheet`         | **Excel-like in-grid editing** — edit cells in place, paste from Excel, no dialog (AG Grid) — **needs import**                                                  | [fsheet.md](fsheet.md)                                                                    |
-| `f-pdfmake`       | Render PDF in iframe                                                                                                                                            | [components-display.md](components-display.md) · [pdfmake.md](pdfmake.md)                 |
-| `f-label`         | Chip/badge for tags, status                                                                                                                                     | [components-display.md](components-display.md)                                            |
-| `f-box`           | Display/edit key-value rows                                                                                                                                     | [components-display.md](components-display.md)                                            |
-| `f-header`        | Large heading (display-1, primary color)                                                                                                                        | [components-display.md](components-display.md)                                            |
-| `f-title`         | Small heading (title, primary color)                                                                                                                            | [components-display.md](components-display.md)                                            |
-| `f-slider`        | Image carousel                                                                                                                                                  | [components-display.md](components-display.md)                                            |
-| `fp-profile`      | User info/profile block                                                                                                                                         | [components-display.md](components-display.md)                                            |
-
-### Table-cell components (`t-*`) — used in f-table `headers`
-
-`t-html` · `t-label` · `t-num` · `t-time` · `t-boolean` · `t-check` (toggle) · `t-text` · `t-select` · `t-combobox` · `t-menu` (context menu) · `t-link` · `t-button` — details: [ui-table-cell-patterns.md](ui-table-cell-patterns.md).
-
-> `header-bar` and `f-window` are internal, runtime-built (header menu, `openWindow` window) — never place them directly in `controls`.
-
-## Components needing JS/CSS imports
-
-**When adding or removing one of these, run `fui import list` and add/remove the matching imports.**
-
-| Component         | Required imports                                                                                         |
-| ----------------- | -------------------------------------------------------------------------------------------------------- |
-| `f-pdfmake`       | `/include/pdfmake/pdfmake.min.js` · `/include/pdfmake/print.min.js` · `/include/pdfmake/vfs_fonts.js`    |
-| `f-file-upload`   | `/include/plupload-2.3.7/plupload.full.min.js`                                                           |
-| `f-image-update`  | `/include/vue-advanced-cropper/index.umd.js` · `/include/vue-advanced-cropper/style.css`                 |
-| `f-qrcode`        | `/include/qrcode/qrcode.min.js`                                                                          |
-| `f-qrcode-reader` | `/include/qrcode/qrcode-reader.min.js`                                                                   |
-| `f-echart`        | `/include/chart/echarts.min.js` · `/include/chart/fechart.js` (**in this order**) — Apache ECharts       |
-| `f-sheet`         | `/include/ag-grid/ag-grid-community.min.js` · `/include/ag-grid/fsheet.js` (**in this order**) — AG Grid |
-| `f-editor`        | `/include/ckeditor5/build/ckeditor.js`                                                                   |
-| `f-editor-dialog` | `/include/ckeditor5/build/ckeditor.js`                                                                   |
-
-> **Bundled, NO import needed:** `v-*` (Vuetify) · `f-table` · `f-dialog` · `f-button` ·
-> `f-date` · `f-time` · `f-search` · `f-menu` · `f-radiobox` · `f-box` · `f-label` · `f-header` ·
-> `f-title` · `f-slider` · `f-excel-reader` — and any component not in the table above.
-
-**Workflow when adding a component with imports** (see `fui import --help`):
-
-1. `fui import list` (project + module) — check existing imports
-2. Missing → `fui import new` for each file
-3. Removing a component → check whether the import is still used elsewhere; if not → `fui import delete`
-
----
-
-## Quick selection rules
-
-- `f-button` over `v-btn` when you need FUI actions (CALL, hotkey, form validation)
-- `f-date` / `f-time` over `v-text-field` + manual date parsing
-- `f-search` over `v-autocomplete` for API search
-- `f-menu` over `v-menu + v-btn` for dropdown actions
-- `f-table` over `v-data-table` for EVERY table — CRUD and view-only (readonly = omit `:update-api`)
-- `f-echart` for every chart type (bar, line, pie, gauge, scatter, radar, sankey, tree, map...)
-- Dialogs: `f-table` `ctrl-update` for inline CRUD; standalone dialog → hand-build `v-dialog` per the standard anatomy (`fui design read fui` §4 + `ui-dialog-patterns.md`); `f-dialog` only for very small forms
+# FUI Component Quick Reference
+
+> Owns: **FUI component catalog, components needing JS/CSS imports, add/remove import workflow**. Per-component details: file in the right column.
+
+Prefer `f-*`; use `v-*` only when no FUI equivalent exists.
+
+| Component         | Use for                                                                                                                                                         | Reference                                                                                 |
+| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| `f-table`         | **Any datatable** — CRUD via dialog form or view-only (readonly = omit `:update-api`); auto-builds headers when `:headers` omitted; totals row via `sum-format` | [component-table.md](component-table.md)                                                  |
+| `f-dialog`        | Modal with form, watch, buttons                                                                                                                                 | [components-dialog.md](components-dialog.md)                                              |
+| `f-window`        | Dialog opening a URL in an iframe                                                                                                                               | [components-dialog.md](components-dialog.md)                                              |
+| `f-button`        | Button with action, hotkey, form validation                                                                                                                     | [components-input.md](components-input.md)                                                |
+| `f-date`          | Date input with picker + typed mask                                                                                                                             | [components-input.md](components-input.md)                                                |
+| `f-time`          | Time input with picker + typed mask                                                                                                                             | [components-input.md](components-input.md)                                                |
+| `f-time-counter`  | Countdown / clock                                                                                                                                               | [components-input.md](components-input.md)                                                |
+| `f-search`        | API-backed autocomplete                                                                                                                                         | [components-input.md](components-input.md)                                                |
+| `f-menu`          | Dropdown button menu with icon/action/link                                                                                                                      | [components-input.md](components-input.md)                                                |
+| `f-radiobox`      | Radio group from items array                                                                                                                                    | [components-input.md](components-input.md)                                                |
+| `f-file-upload`   | File upload (Plupload, progress dialog)                                                                                                                         | [components-input.md](components-input.md)                                                |
+| `f-image-update`  | Image upload + crop                                                                                                                                             | [components-input.md](components-input.md)                                                |
+| `f-excel-reader`  | Excel/CSV → JSON (pick sheet, skip first N rows, name columns)                                                                                                  | [components-input.md](components-input.md)                                                |
+| `f-qrcode`        | Render QR code                                                                                                                                                  | [components-input.md](components-input.md)                                                |
+| `f-qrcode-reader` | Read QR via camera                                                                                                                                              | [components-input.md](components-input.md)                                                |
+| `f-editor`        | Rich text editor (CKEditor 5)                                                                                                                                   | [components-dialog.md](components-dialog.md)                                              |
+| `f-editor-dialog` | Rich text editor in a modal                                                                                                                                     | [components-dialog.md](components-dialog.md)                                              |
+| `f-echart`        | **Charts** — ECharts V5: bar, line, pie, scatter, gauge, radar, heatmap, sankey, tree, map, graph...                                                            | [components-echart.md](components-echart.md) · [echart-templates.md](echart-templates.md) |
+| `f-sheet`         | **Excel-like in-grid editing** — edit cells in place, paste from Excel, no dialog (AG Grid) — **needs import**                                                  | [fsheet.md](fsheet.md)                                                                    |
+| `f-pdfmake`       | Render PDF in iframe                                                                                                                                            | [components-display.md](components-display.md) · [pdfmake.md](pdfmake.md)                 |
+| `f-label`         | Chip/badge for tags, status                                                                                                                                     | [components-display.md](components-display.md)                                            |
+| `f-box`           | Display/edit key-value rows                                                                                                                                     | [components-display.md](components-display.md)                                            |
+| `f-header`        | Large heading (display-1, primary color)                                                                                                                        | [components-display.md](components-display.md)                                            |
+| `f-title`         | Small heading (title, primary color)                                                                                                                            | [components-display.md](components-display.md)                                            |
+| `f-slider`        | Image carousel                                                                                                                                                  | [components-display.md](components-display.md)                                            |
+| `fp-profile`      | User info/profile block                                                                                                                                         | [components-display.md](components-display.md)                                            |
+
+### Table-cell components (`t-*`) — used in f-table `headers`
+
+`t-html` · `t-label` · `t-num` · `t-time` · `t-boolean` · `t-check` (toggle) · `t-text` · `t-select` · `t-combobox` · `t-menu` (context menu) · `t-link` · `t-button` — details: [ui-table-cell-patterns.md](ui-table-cell-patterns.md).
+
+> `header-bar` and `f-window` are internal, runtime-built (header menu, `openWindow` window) — never place them directly in `controls`.
+
+## Components needing JS/CSS imports
+
+**When adding or removing one of these, run `fui import list` and add/remove the matching imports.**
+
+| Component         | Required imports                                                                                         |
+| ----------------- | -------------------------------------------------------------------------------------------------------- |
+| `f-pdfmake`       | `/include/pdfmake/pdfmake.min.js` · `/include/pdfmake/print.min.js` · `/include/pdfmake/vfs_fonts.js`    |
+| `f-file-upload`   | `/include/plupload-2.3.7/plupload.full.min.js`                                                           |
+| `f-image-update`  | `/include/vue-advanced-cropper/index.umd.js` · `/include/vue-advanced-cropper/style.css`                 |
+| `f-qrcode`        | `/include/qrcode/qrcode.min.js`                                                                          |
+| `f-qrcode-reader` | `/include/qrcode/qrcode-reader.min.js`                                                                   |
+| `f-echart`        | `/include/chart/echarts.min.js` · `/include/chart/fechart.js` (**in this order**) — Apache ECharts       |
+| `f-sheet`         | `/include/ag-grid/ag-grid-community.min.js` · `/include/ag-grid/fsheet.js` (**in this order**) — AG Grid |
+| `f-editor`        | `/include/ckeditor5/build/ckeditor.js`                                                                   |
+| `f-editor-dialog` | `/include/ckeditor5/build/ckeditor.js`                                                                   |
+
+> **Bundled, NO import needed:** `v-*` (Vuetify) · `f-table` · `f-dialog` · `f-button` ·
+> `f-date` · `f-time` · `f-search` · `f-menu` · `f-radiobox` · `f-box` · `f-label` · `f-header` ·
+> `f-title` · `f-slider` · `f-excel-reader` — and any component not in the table above.
+
+**Workflow when adding a component with imports** (see `fui import --help`):
+
+1. `fui import list` (project + module) — check existing imports
+2. Missing → `fui import new` for each file
+3. Removing a component → check whether the import is still used elsewhere; if not → `fui import delete`
+
+---
+
+## Quick selection rules
+
+- `f-button` over `v-btn` when you need FUI actions (CALL, hotkey, form validation)
+- `f-date` / `f-time` over `v-text-field` + manual date parsing
+- `f-search` over `v-autocomplete` for API search
+- `f-menu` over `v-menu + v-btn` for dropdown actions
+- `f-table` over `v-data-table` for EVERY table — CRUD and view-only (readonly = omit `:update-api`)
+- `f-echart` for every chart type (bar, line, pie, gauge, scatter, radar, sankey, tree, map...)
+- Dialogs: `f-table` `ctrl-update` for inline CRUD; standalone dialog → hand-build `v-dialog` per the standard anatomy (`fui design read fui` §4 + `ui-dialog-patterns.md`); `f-dialog` only for very small forms