@fui-org/fui-cli 1.3.1 → 2.0.0

package/skills/fui-skill/references/coding-standards.md

@@ -1,33 +1,36 @@
 # FUI Coding Standards
 
-> File này sở hữu: **chuẩn code chung: đặt tên, quy ước `<style scoped>` trong `.vue` (scope thủ công), cấm backtick trong `<template>`, reusable API**. Quy tắc thiết kế component chi tiết xem [component-design.md](component-design.md).
+> Owns: **general code standards: naming, `<style scoped>` in `.vue` (manual scoping), no backticks in `<template>`, reusable APIs**. Detailed component design rules: [component-design.md](component-design.md).
 
-## 1. Naming Conventions
+## 1. Naming
 
 ### Components (`components/`)
--   **Prefix**: Use `uc-` (User Component) for custom module components to distinguish from standard FUI components (`f-`, `t-`).
--   **Format**: Kebab-case (e.g., `uc-trangthai-sukien.vue`, `uc-user-profile.vue`).
--   **Props**: Use camelCase in script, kebab-case in templates (e.g., `userProfile` -> `:user-profile`).
--   **Prefer reusable APIs**: Default to generic props, emits, and slots so the component can be reused across modules or screens.
--   **Avoid overfitting names**: Prefer neutral contracts like `items`, `value`, `label`, `loading`, `readonly`, `disabled`, `options`, `config` unless the business domain truly requires a specific prop name.
--   **Push orchestration upward**: Keep API calls, route changes, and page-specific coordination in `module.json` or the parent when possible. Let the component focus on presentation and local interaction.
--   **Emit upward**: Prefer `$emit(...)` for `input`, `change`, `select`, `submit`, `remove`, or explicit action events rather than mutating parent-owned state.
+
+- **Prefix** `uc-` (User Component) for custom components, distinct from standard FUI `f-`, `t-`.
+- **Kebab-case** file names (e.g. `uc-trangthai-sukien.vue`, `uc-user-profile.vue`).
+- **Props**: camelCase in script, kebab-case in templates (`userProfile` -> `:user-profile`).
+- **Reusable APIs**: default to generic props, emits and slots so the component works across modules/screens.
+- **No overfitted names**: prefer neutral contracts (`items`, `value`, `label`, `loading`, `readonly`, `disabled`, `options`, `config`) unless the domain truly needs a specific name.
+- **Push orchestration up**: API calls, route changes and page coordination stay in `module.json` or the parent; the component handles presentation and local interaction.
+- **Emit up**: prefer `$emit(...)` for `input`, `change`, `select`, `submit`, `remove` or explicit action events over mutating parent-owned state.
 
 ### CSS Classes
--   **`<style scoped>` in `.vue` is allowed** (saved server-side as `ComCSS`), but `scoped` has **no real scoping effect** — FUI only concatenates `ComCSS` from every component in the module into one global stylesheet (`ComponentCSSBuild()`), no AST transform, no `data-v-xxxx` attribute injection. **Every selector must be manually scoped**: give the component's root template element a unique class matching the component name (kebab-case, e.g. `uc-invoice-list`), then write every rule as a descendant selector starting from that class (`.uc-invoice-list__title`, never a bare `.title`). See [component-design.md](component-design.md) for a full example.
--   **Style Placement**: Component-local CSS → `<style scoped>` in the `.vue` file (with manual scoping above). Module-wide CSS → `style.css` (publish via `module_publish_css`). `header.html` is still valid for CSS but no longer the only option.
--   **Vuetify Utilities**: Prioritize Vuetify helper classes (e.g., `ma-2`, `pa-0`, `d-flex`, `primary--text`).
--   **Custom Classes**: Use meaningful prefixed names (e.g., `ep-hero`, `ep-field-grid`). Avoid generic names like `.box` or `.red`.
--   **State Classes**: Use descriptive names for state (e.g., `.is-active`, `.has-error`).
+
+- **`<style scoped>` in `.vue` is allowed** (saved server-side as `ComCSS`) but `scoped` has **no real effect** — FUI just concatenates every component's `ComCSS` in the module into one global stylesheet (`ComponentCSSBuild()`): no AST transform, no `data-v-xxxx`. **Scope every selector manually**: give the root template element a unique class matching the component name (kebab-case, e.g. `uc-invoice-list`) and write every rule under it (`.uc-invoice-list__title`, never bare `.title`). Full example: [component-design.md](component-design.md).
+- **Placement**: component CSS → `<style scoped>` in the `.vue` (manually scoped). Module-wide CSS → `style.css` (publish with `fui module publish css`). `header.html` still works for CSS but is no longer the only option.
+- **Vuetify utilities first** (`ma-2`, `pa-0`, `d-flex`, `primary--text`).
+- **Custom classes**: meaningful prefixed names (`ep-hero`, `ep-field-grid`); avoid generic `.box`, `.red`.
+- **State classes**: descriptive (`.is-active`, `.has-error`).
 
 ### Action Keys (`module.json`)
--   **API Actions**: Predix with `api` (e.g., `apiGetDSSuKien`, `apiUpdateUser`).
--   **Event Handlers**: Prefix with `handle` (e.g., `handleOpenReport`, `handleSubmit`).
--   **Dialog Actions**: Prefix with verb (e.g., `openUploadDialog`, `closeSettings`).
 
-## 2. Menu Configuration (`set.menu`)
+- **API actions**: prefix `api` (`apiGetDSSuKien`, `apiUpdateUser`).
+- **Event handlers**: prefix `handle` (`handleOpenReport`, `handleSubmit`).
+- **Dialog actions**: prefix a verb (`openUploadDialog`, `closeSettings`).
+
+## 2. Menu (`set.menu`)
 
-Define the application menu in the `set` object of `module.json`.
+Define the app menu in `module.json`'s `set` object.
 
 ```json
 "menu": [
@@ -58,55 +61,52 @@ Define the application menu in the `set` object of `module.json`.
 
 ## 3. Project Structure
 
--   **Canonical module structure**: Follow [module-structure.md](module-structure.md) as the default module layout in both workspace and chat contexts. In workspace-aware environments, apply it to real local files. In chat contexts, use it to virtualize the same module structure in the response.
--   **Required core files**: Keep `_info.json` and `module.json` at module root.
--   **`components/`**: Only place `.vue` files here. Do not sub-folder unless strictly necessary (FUI auto-scans this root).
--   **`components/_components.json`**: Maintain component registry when using `uc-*` components.
--   **`header.html`**: Still valid for CSS, but component CSS should prefer `<style scoped>` in the `.vue` (manually scoped) and module-wide CSS should prefer `style.css`.
--   **`module.json`**: Keep this file clean. Move large static lists to the database or separate JSON files if supported.
+- **Canonical layout**: follow [module-structure.md](module-structure.md) in workspace and chat contexts — real local files with workspace access; in chat, mirror the same structure in the response.
+- **Required**: `_info.json` and `module.json` at module root.
+- **`components/`**: only `.vue` files; no subfolders unless strictly necessary (FUI scans this root).
+- **`components/_components.json`**: keep the registry when using `uc-*` components.
+- **`header.html`**: still valid for CSS, but prefer manually scoped `<style scoped>` in `.vue` for component CSS and `style.css` for module-wide CSS.
+- **`module.json`**: keep clean; move large static lists to the DB or separate JSON files if supported.
 
 ## 4. Best Practices
 
--   **Data Binding**: Avoid complex logic in JSON attributes. Use computed properties in components or simpler `vueData` structures.
--   **Event Handling**: Use `CALL(vueData.actionName)` for all complex interactions. Avoid inline JS like `vueData.count++` for anything beyond simple toggles.
--   **Mobile Responsiveness**: Always configure `configForm.xs` and `configForm.md` for responsive form widths.
+- **Data binding**: no complex logic in JSON attributes; use computed properties in components or simpler `vueData` structures.
+- **Events**: use `CALL(vueData.actionName)` for complex interactions; inline JS like `vueData.count++` only for simple toggles.
+- **Responsive**: always set `configForm.xs` and `configForm.md` for form widths.
 
 ## 5. Component Registration (`_components.json`)
 
-Components are registered using an **upsert pattern**:
+**Upsert pattern:**
 
--   **New component** (before publish): Only `comName` is required. Do NOT manually assign `comID`.
-    ```json
-    [
-      { "comName": "hr-employee-profile" }
-    ]
-    ```
--   **After publish & sync**: The server auto-assigns `comID`. The file gets updated on sync:
-    ```json
-    [
-      { "comID": 7813, "comName": "hr-employee-profile" }
-    ]
-    ```
+- **New component** (before publish): only `comName`. Do NOT assign `comID`.
+  ```json
+  [{ "comName": "hr-employee-profile" }]
+  ```
+- **After publish & sync**: the server assigns `comID`; sync updates the file:
+  ```json
+  [{ "comID": 7813, "comName": "hr-employee-profile" }]
+  ```
 
-> **Rule**: Never manually create or modify `comID`. It is server-generated.
+> **Rule**: never create or modify `comID` manually — it is server-generated.
 
 ## 6. Vue Component Design
 
-Xem toàn bộ quy tắc thiết kế `uc-*.vue` component tại [component-design.md](component-design.md), bao gồm:
-- Không dùng `components: {}` để đăng ký
-- `<style scoped>` trong file `.vue` phải tự scope thủ công (xem mục CSS Classes ở trên)
-- Không dùng backtick trong `<template>`
-- Không dùng `v-dialog` — dùng cấu trúc `v-overlay` thay thế
-- Cấu trúc bắt buộc cho dialog component
+Full `uc-*.vue` rules in [component-design.md](component-design.md), including:
+
+- No `components: {}` registration
+- `<style scoped>` in `.vue` must be manually scoped (see CSS Classes)
+- No backticks in `<template>`
+- No `v-dialog` — use the `v-overlay` structure
+- Required structure for dialog components
 
 ## 7. Complex Module Architecture
 
-When a module's `module.json` controls exceed ~200 lines:
+When `module.json` controls exceed ~200 lines:
 
--   **Extract to Vue component**: Move the UI into a `.vue` component. Keep `module.json` lean (data/API only + a single component call in `controls`).
--   **Props binding**: Pass all data from `module.json` via props. Use kebab-case for prop names in templates (`:nhan-vien="nhanVien"`).
--   **Design for reuse first**: Before naming props or methods, check whether the component can be expressed as a generic list, card, dialog body, filter panel, summary block, or form section reused by other modules.
--   **Configurable states**: Expose loading, empty, disabled, and readonly behavior through props or slots instead of hardcoding one workflow.
--   **Sticky headers**: When combining multiple sticky elements (e.g., hero + tabs), wrap them in **one parent div** with `position: sticky` instead of making each element sticky individually.
--   **Tab navigation vs Accordion**: For 5+ sections of data, prefer horizontal `v-tabs` over `v-expansion-panels`. Tabs show one section at a time, reduce cognitive overload, and support swipe gestures on mobile.
--   **Swipe gestures**: Attach `touchstart`/`touchend` listeners on the **outermost wrapper** (not on content area) so swipe works regardless of content height.
+- **Extract to a Vue component**: move UI into a `.vue`; `module.json` keeps data/API plus one component call in `controls`.
+- **Props binding**: pass all data from `module.json` via props, kebab-case in templates (`:nhan-vien="nhanVien"`).
+- **Design for reuse first**: before naming props/methods, check whether it can be a generic list, card, dialog body, filter panel, summary block or form section reusable elsewhere.
+- **Configurable states**: expose loading, empty, disabled, readonly via props or slots, not a hardcoded workflow.
+- **Sticky headers**: for multiple sticky elements (e.g. hero + tabs), wrap them in **one parent div** with `position: sticky`, not each element.
+- **Tabs vs accordion**: 5+ sections → horizontal `v-tabs` over `v-expansion-panels` (one section at a time, less overload, swipe on mobile).
+- **Swipe gestures**: attach `touchstart`/`touchend` on the **outermost wrapper** (not the content area) so swipe works regardless of content height.