@fui-org/fui-cli 1.2.0 → 1.3.1

package/skills/fui-skill-cli/references/component-design.md

@@ -0,0 +1,448 @@
+# FUI Vue Component Design Rules
+
+> Owns: **`uc-*.vue` rules: module/project scope, no `name:`/`components:{}`, props/emits/slots, no `_injectStyle`, manual `<style scoped>` scoping, verification (`fui component preview`, push project components before module render), `{projectId}/COMPONENTS.md`**. Approved classes/props: [controls-styling-vocabulary.md](controls-styling-vocabulary.md).
+
+Mandatory for every `uc-*.vue`, dialog components included.
+
+---
+
+## 1. Two scopes: module vs project
+
+|                | Module-scope                                         | Project-scope (global)                    |
+| -------------- | ---------------------------------------------------- | ----------------------------------------- |
+| **File**       | `{projectId}/modules/{moduleId}/components/uc-*.vue` | `{projectId}/components/uc-*.vue`         |
+| **Registry**   | `modules/{moduleId}/components/_components.json`     | `{projectId}/components/_components.json` |
+| **Visible in** | That module only                                     | **All modules in the project**            |
+| **Auto-load**  | In its module                                        | Automatic — **nothing to declare**        |
+| **Use when**   | Used by one module                                   | Reused across modules                     |
+
+### Choosing scope
+
+```
+Component này sẽ dùng ở nhiều module? → project-scope
+Component chỉ dùng trong một module?   → module-scope
+```
+
+### Commands per scope
+
+| Operation                  | Module-scope                                        | Project-scope (global)                             |
+| -------------------------- | --------------------------------------------------- | -------------------------------------------------- |
+| **Create** (not on server) | `fui component new <name>` — uses session module    | `fui component new <name> -p <pid>` — NO module    |
+| **Update** (on server)     | `fui component update <name>` — uses session module | `fui component update <name> -p <pid>` — NO module |
+| **Delete**                 | `fui component delete <name>` — uses session module | `fui component delete <name> -p <pid>` — NO module |
+| **Read source**            | `fui component get <name> -p <pid> -m <mid>`        | `fui component get <name> -p <pid>` — omit module  |
+| **Sync list**              | `fui component list -p <pid> -m <mid>`              | `fui component list -p <pid>` — omit module        |
+| **Workspace file**         | `{moduleDir}/components/uc-foo.vue`                 | `{projectDir}/components/uc-foo.vue`               |
+
+**Single rule:** module given → module-scope · no module, only project → project-scope. Flags: `fui component --help`.
+
+**Create ≠ update — no implicit upsert.** Both read the **local** `.vue` (must exist on disk) and derive `ComID` from `_components.json` (never pass it):
+
+- `fui component new` — INSERT only. Refreshes `_components.json` **from the server first**, then checks the name; duplicate = **hard error** (INSERT on a stale cache creates **two same-name records**, unfixable from fui). Re-syncs after to get the real `ComID`.
+- `fui component update` — UPDATE only. No `ComID` = **hard error**, never creates: never created (→ `fui component new`) or stale cache (→ `fui component list`, retry).
+
+`fui component delete` looks up ComID in local `_components.json`; stale → `fui component list` first.
+
+**`fui module publish html` excludes project-scope components** — push them separately (`fui component new`/`update`).
+
+---
+
+## 1a. Existing project components — `{projectId}/COMPONENTS.md`
+
+Before designing a project-scope component, **check `{projectId}/COMPONENTS.md`** (if present): existing project `uc-*.vue` with purpose and main props. Don't rebuild one that exists.
+
+```
+{FUI_MCP_WORKDIR}/{projectId}/COMPONENTS.md    ← kiểm tra TRƯỚC khi tạo component project-scope mới
+```
+
+**Accumulation:** after creating/updating a reusable project component, append an entry; no file → create with:
+
+```markdown
+# {projectId} — Danh sách component project-scope
+
+## uc-ten-component
+
+**Mục đích:** mô tả ngắn gọn component dùng để làm gì  
+**Props:** `propA` (kiểu, mặc định) · `propB` (kiểu, mặc định)  
+**Events:** `@eventName` — khi nào phát  
+**Ghi chú:** điều gì cần biết khi dùng (nếu có)
+```
+
+> Mirrors `{projectId}/DESIGN.md` ([design-modes.md](design-modes.md) §2-3). **Never auto-remove entries** — remove only after `fui component delete` removed it from the server.
+
+---
+
+## 2. Naming and file layout
+
+- Prefix `uc-` (User Component; vs `f-*` FUI runtime, `v-*` Vuetify), kebab-case: `uc-trangthai-sukien.vue`, `uc-user-profile.vue`
+- Only in `components/` at module or project root; no subfolders
+- Registry `components/_components.json`: only `comName`, never set `comID`
+
+---
+
+## 3. Registration — NO `components: {}`, NO `name:`
+
+FUI auto-registers every `uc-*.vue` **globally**. Never declare `components: { ... }` (doesn't work in FUI) or `name:` (FUI derives it from the filename; may conflict):
+
+```js
+// ❌ SAI — không cần và có thể gây xung đột
+export default {
+  name: 'uc-user-card',
+  props: { ... }
+}
+
+// ✅ ĐÚNG — bỏ name, FUI tự resolve từ tên file
+export default {
+  props: { ... }
+}
+```
+
+```js
+// ❌ SAI — không dùng trong FUI
+export default {
+  components: { "uc-user-card": UcUserCard },
+};
+
+// ✅ ĐÚNG — dùng trực tiếp tag trong template
+// <uc-user-card :data="data" />
+```
+
+---
+
+## 4. Props
+
+- `script`: camelCase (`userName`, `itemList`); `template`: kebab-case (`:user-name="userName"`)
+- Array/Object defaults use `function()`, not arrow functions:
+
+```js
+// ❌ SAI
+props: { items: { default: () => [] } }
+
+// ✅ ĐÚNG
+props: { items: { default: function() { return [] } } }
+```
+
+- Prefer neutral reusable names (`items`, `value`, `label`, `loading`, `readonly`, `disabled`, `options`, `config`), not screen-specific ones
+
+---
+
+## 5. Emits
+
+- Emit to the parent; never mutate parent state
+- Standard: `input`, `change`, `select`, `submit`, `remove`, `action`
+- Dialog components always close with `('input', false)` — Vue 2 `v-model` compatible
+
+---
+
+## 6. Template syntax constraints
+
+### No backticks in `<template>`
+
+Breaks in Vue 2 templates; concatenate:
+
+```html
+<!-- ❌ SAI -->
+:label="`Total (${items.length})`"
+
+<!-- ✅ ĐÚNG -->
+:label="'Total (' + items.length + ')'"
+```
+
+### No `@` shorthand in JSON
+
+`module.json`: always `v-on:click`, never `@click`. `.vue` templates: `@click` is fine.
+
+### Vue 2 needs a single root element
+
+```html
+<!-- ✅ ĐÚNG -->
+<template>
+  <div>
+    <!-- nội dung -->
+  </div>
+</template>
+```
+
+---
+
+## 7. Style & class — use existing Vuetify classes, DON'T invent
+
+**Use Vuetify utility classes for ALL spacing/flex/text/color/size. New class only when truly special** (effect/layout Vuetify lacks) — invented classes break consistency.
+
+### ❌ NEVER inject CSS via JavaScript
+
+No `<style>` created in JS and appended to `document.head` (`_injectStyle`) — severe anti-pattern (dodges the no-`<style>` rule, spawns invented classes):
+
+```js
+// ❌ SAI NGHIÊM TRỌNG — không bao giờ làm thế này trong .vue
+methods: {
+  _injectStyle: function() {
+    var s = document.createElement('style')
+    s.textContent = ['.smg-root{...}', '.smg-card{...}', '.smg-badge{...}', ...].join('')
+    document.head.appendChild(s)   // ❌ bơm CSS + hàng loạt class tự chế
+  }
+}
+```
+
+`<style scoped>` is allowed for custom CSS (rarely needed), but **does not scope**: FUI concatenates every module component's `ComCSS` into ONE stylesheet (`ComponentCSSBuild()`) — no SFC compile, no `data-v-xxxx`. **Scope manually**:
+
+1. Template root gets a class = component name (`uc-invoice-list` → `class="uc-invoice-list"`).
+2. EVERY selector starts from that class — **no bare selectors** (`.title`, `.header`...); they leak into every component in the module.
+
+```vue
+<template>
+  <div class="uc-invoice-list">
+    <div class="uc-invoice-list__toolbar">
+      <span class="uc-invoice-list__title">{{ title }}</span>
+    </div>
+    <f-table class="uc-invoice-list__table" :items="rows"></f-table>
+  </div>
+</template>
+
+<style scoped>
+.uc-invoice-list__toolbar {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+}
+.uc-invoice-list__title {
+  font-weight: 600;
+  font-size: 14px;
+}
+.uc-invoice-list__table {
+  margin-top: 8px;
+}
+</style>
+```
+
+```vue
+<!-- ❌ SAI — selector trần, đụng với component khác cùng module có class .title/.toolbar -->
+<style scoped>
+.title {
+  font-weight: 600;
+}
+.toolbar {
+  display: flex;
+}
+</style>
+```
+
+Module-wide CSS → `style.css` (`fui module publish css`); `header.html` still works but isn't the only option.
+
+### Before adding a class → check the approved vocabulary
+
+Allowed Vuetify classes/props (spacing, flex, text, color, radius, elevation, breakpoint, size), priority, when a custom class is allowed → [controls-styling-vocabulary.md](controls-styling-vocabulary.md) §3. Applies unchanged in `.vue`, **except** no FUI grid `w`/`col` (`module.json` syntax translated by the runtime) — write the Vuetify grid directly.
+
+**Grid syntax DIFFERS by framework** — FUI V2 = Vuetify 1.5, FUI V3 = Vuetify 3 (canonical: [controls-patterns.md](controls-patterns.md) §Vuetify version):
+
+|                    | V2 (Vuetify 1.5)          | V3 (Vuetify 3)                                                                                                                                                                                               |
+| ------------------ | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Columns            | `v-layout` > `v-flex xs8` | `v-row` > `v-col cols="8"`                                                                                                                                                                                   |
+| `v-flex`           | ✅                        | ❌ **does not exist** — renders as an inert HTML element: no error, no `[Vue warn]`, just **layout gone**                                                                                                    |
+| `v-layout`         | ✅ grid row               | ⚠️ **exists with a different meaning**: app layout wrapper (with `v-main`, as `fastproject-3.0.js` uses), NOT a grid row. Using it instead of `v-row` gives a flex container without grid gutter/breakpoints |
+| bare prop `shrink` | ✅ (`v-flex` prop)        | ❌ no such prop → inert DOM attribute. Use `class="shrink"`                                                                                                                                                  |
+
+§8 is **V3** (`v-row`/`v-col`); V2 projects use `v-layout`/`v-flex`. Silent breakage both ways: `v-flex` in V3 **shows content with wrong layout**, nothing reports it. Fixing an old component → `fui component preview` on **the project's framework** before pushing.
+
+Component-specific CSS → its own `<style scoped>`, manually scoped — not `header.html` unless shared by several components/the module.
+
+---
+
+## 8. Standard dialog in `uc-*.vue` — STANDARD TEMPLATE
+
+EVERY form dialog: `v-dialog` + `v-card` with these **fixed conventions**. Vuetify utility classes only — no invented classes, no `style`.
+
+```html
+<v-dialog v-model="editDialog" max-width="600">
+  <v-card>
+    <!-- Tiêu đề: px-3 pt-2 pb-3, subtitle-1 font-weight-bold, nút X bên phải -->
+    <v-card-title class="d-flex align-center px-3 pt-2 pb-3 subtitle-1 font-weight-bold">
+      {{ editItem.RoundID ? 'Chỉnh sửa vòng thi' : 'Thêm vòng thi mới' }}
+      <v-spacer></v-spacer>
+      <v-btn icon @click="editDialog = false"><v-icon>mdi-close</v-icon></v-btn>
+    </v-card-title>
+
+    <!-- Nội dung: px-3 py-1; field dùng outlined dense hide-details, chia cột bằng v-row/v-col -->
+    <v-card-text class="px-3 py-1">
+      <v-row>
+        <v-col cols="8">
+          <v-text-field v-model="editItem.RoundName" label="Tên vòng thi" hide-details outlined dense></v-text-field>
+        </v-col>
+        <v-col cols="4">
+          <v-text-field
+            v-model.number="editItem.RoundOrder"
+            label="Thứ tự"
+            type="number"
+            hide-details
+            outlined
+            dense
+          ></v-text-field>
+        </v-col>
+      </v-row>
+    </v-card-text>
+
+    <!-- Hàng cuối: action căn phải, button rộng tự nhiên; action phụ text, action chính primary -->
+    <v-card-actions class="pa-3">
+      <v-spacer></v-spacer>
+      <v-btn text @click="resetForm">Đặt lại</v-btn>
+      <v-btn color="primary" elevation="0" :loading="saving" @click="saveRound">Lưu</v-btn>
+    </v-card-actions>
+  </v-card>
+</v-dialog>
+```
+
+### Mandatory conventions (don't change arbitrarily)
+
+| Part             | Class/prop                                                             | Note                                                                              |
+| ---------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| `v-dialog`       | `max-width="600"`                                                      | 600 normal form; 400 small; 800–900 wide form                                     |
+| `v-card-title`   | `d-flex align-center px-3 pt-2 pb-3 subtitle-1 font-weight-bold`       | Compact title + X button (`v-btn icon` → `mdi-close`) on the right via `v-spacer` |
+| `v-card-text`    | `px-3 py-1`                                                            | Consistent content padding                                                        |
+| Input fields     | `outlined dense hide-details`                                          | Compact, equal height; columns via `v-row` + `v-col cols="N"`                     |
+| `v-card-actions` | **Last row**; `pa-3` + `v-spacer` before buttons                       | All actions right-aligned                                                         |
+| Button width     | No `block`, `width`, grow class or stretched column wrapper            | Natural width from label                                                          |
+| Primary button   | At most one with `color="primary" elevation="0"` + `:loading="saving"` | Filled to show priority; `:loading` during API call                               |
+| Secondary button | `text`, no background `color`                                          | Minor actions; understated                                                        |
+
+- Mode-dependent title: `{{ editItem.ID ? 'Chỉnh sửa' : 'Thêm mới' }}`.
+- Numbers: `v-model.number` + `type="number"`.
+- Close: `@click="dialogVar = false"`; also set `false` in the callback after a successful save.
+- Keep default icon size; never add `small`/`:small` to `v-icon` or icon buttons.
+
+### Variants
+
+- **Toolbar header** (color/icon emphasis): replace `v-card-title` with `v-toolbar dense flat` + `v-toolbar-title`.
+- **Fullscreen** (large/multi-area form): `<v-dialog v-model="..." fullscreen>` + `v-toolbar` header, content in `v-container class="grid-list-md"`.
+
+---
+
+## 9. Design for reuse
+
+- Shape as list, card, dialog body, filter panel, summary block or form section where possible
+- Expose loading/empty/disabled/readonly via props/slots, don't hardcode a workflow
+- API calls, routing, permissions stay in `module.json` or parent — component = presentation
+- module.json `controls` > ~200 lines → extract UI to a Vue component; module.json keeps data/API
+
+---
+
+## 10. No `f-dialog` inside a component template
+
+`f-dialog` works only directly in the module's `controls` JSON. In `uc-*.vue` use the §8 v-dialog.
+
+---
+
+## 11. `<script>` syntax limits
+
+### No `async / await / finally`
+
+Unsupported by the FUI `.vue` parser; use callbacks:
+
+```js
+// ❌ SAI
+async mounted() {
+    const res = await fetch(url)
+}
+
+// ✅ ĐÚNG
+mounted() {
+    ajaxCALL(url, {}, function(res) { ... })
+}
+```
+
+### No template literals (backticks) in `<script>`
+
+Only work in standalone `script.js`:
+
+```js
+// ❌ SAI — trong .vue <script>
+var url = `/api/Student/${this.studentID}`;
+
+// ✅ ĐÚNG
+var url = "/api/Student/" + this.studentID;
+```
+
+---
+
+## 12. Reuse `defaultfunction.js` — DON'T rewrite
+
+**Before writing logic (API call, confirm, notify, format, group, copy...) → check [default-function.md](default-function.md).** Write your own only if nothing fits.
+
+### API calls — `ajaxCALL` (NOT hand-rolled `fetch`/`axios`/`$.ajax`)
+
+`fetch` fails cross-domain (CORS/credentials). `ajaxCALL` handles credentials, Bearer token and base domain (`v_Set.apiDomain`) — don't prepend it.
+
+```js
+// ❌ SAI
+fetch(url, { method: 'POST', body: JSON.stringify(data) })
+    .then(r => r.json()).then(res => { ... })
+
+// ✅ ĐÚNG — ajaxCALL(URL, DATA, successCb, errorCb, header)
+ajaxCALL('spAPI_RoundList', { ContestID: this.contestID }, function(res) {
+    // res đã parse JSON (json_data tự parse)
+}, function(err) {
+    // tuỳ chọn — mặc định ajaxCALL đã showMessage lỗi
+})
+```
+
+### Confirm — `confirm` (NOT `window.confirm`)
+
+```js
+confirm({
+    title: 'Xác nhận xoá',
+    message: 'Bạn có chắc muốn xoá vòng thi này?',
+    action: function() { ajaxCALL('spAPI_RoundDelete', { RoundID: id }, function(){ ... }); }
+});
+```
+
+### Notify — `showMessage` or `Vue.$toast`
+
+```js
+showMessage({ title: "Đã lưu thành công" }); // hộp thoại
+showMessage({ title: "Lỗi", message: "...", type: "red" });
+Vue.$toast.success("Đã lưu", { position: "top" }); // toast góc màn hình
+```
+
+### Other common helpers (don't rewrite)
+
+`groupBy` · `findInArray` · `jsonToExcel` (Excel export) · `printPDF` · `copyToClipboard` · `openWindow` · `pushRouter` · `rightTest` (permission check) · `generateID` · `capacityText` · `buildHeader` (auto f-table headers). Details: [default-function.md](default-function.md).
+
+> Globals — never add a CDN for them: `_` (Lodash: `_.groupBy`, `_.sumBy`, `_.cloneDeep`...), `moment` (dates), `numeral` (numbers).
+
+---
+
+## 13. Verify with `fui component preview` BEFORE assembling into the module
+
+Seen only after assembly, component bugs and assembly bugs mix. `fui component preview` renders **one component** on its own page from the **local** `.vue` (no push needed) with sample data passed directly.
+
+```
+fui component preview uc-invoice-list -p <pid> --cases '[
+  { "name": "danh sách rỗng",  "props": { "items": [] } },
+  { "name": "có dữ liệu",      "props": { "items": [ {...}, {...} ], "title": "Hoá đơn" } },
+  { "name": "click chọn dòng", "props": { "items": [...] },
+    "scenario": [ { "click": "Xem" }, { "assert": "vueData.selected != null" } ] }
+]'
+# -p only → project-scope; add -m <mid> → module-scope (same inference as fui component new/update)
+# devices default: desktop + mobile
+```
+
+- **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`.
+- `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.
+
+### Project components: MUST push before rendering a module that uses them
+
+`fui module simulate --render` builds the project layer from the **server** bundle; unpushed local edits **don't appear** (screenshot lies). So `--render` **hard-blocks** (no override) when a local project component differs from the server bundle.
+
+```
+sửa uc-*.vue cấp project
+  → fui component preview   (kiểm chứng bản local, chưa push)
+  → fui component new       (lần đầu) hoặc fui component update (các lần sau) — push lên server
+  → fui module simulate --render   ← chỉ chạy được sau khi đã push
+```
+
+Blocked and **server is newer** (edited in web IDE) → `fui project sync`; **don't push over it** (erases their work).
+
+**Module-level** components are exempt: the module layer renders from local files.

package/skills/fui-skill-cli/references/component-quickref.md

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