|
| 1 | +--- |
| 2 | +name: opensilex-vue |
| 3 | +description: Creates, modifies and reviews Vue 3 components of the OpenSILEX front so that they follow the team conventions of the technical documentation page vuejs-file-structure.md - block order, script setup with typed defineEmits, defineProps and defineModel, Public and Private regions, typed template refs, event handlers, no any, Naive UI instead of Bootstrap, reuse of the shared common/ components (TableAsyncView, SearchFiltersSidebar, FormSelector, action buttons), en/fr i18n. Ships a conventions checker. Use whenever a .vue component or its TypeScript is written, ported, fixed or reviewed in opensilex-front or in an extension module (list, filters, form, modal, detail page, selector), even when the word "conventions" is not used. Also trigger on French requests such as "crée un composant", "relis ce composant", "revue du composant Vue", "respecte les conventions Vue". |
| 4 | +--- |
| 5 | + |
| 6 | +# OpenSILEX Vue components |
| 7 | + |
| 8 | +This skill sets **how a component is written**. The file structure (regions and their order, event handlers, typing, |
| 9 | +JSDoc) comes from the technical documentation page |
| 10 | +[`vuejs-file-structure.md`](../../../opensilex-doc/src/main/resources/technical-documentation/opensilex-front/vuejs-file-structure.md). |
| 11 | +That page is the reference; this skill adds the rules for UI, i18n and reuse. When the page changes, align |
| 12 | +this skill with it. |
| 13 | + |
| 14 | +The host front lives in `opensilex-front/front/src`, the shared building blocks in `components/common/`. The platform |
| 15 | +side (the `$opensilex` plugin, routes and menus in `opensilex.front.yml`, extension modules, build) is documented next to |
| 16 | +that page (`plugin.md`, `router.md`, `vite.md`) and in `opensilex-module/module-frontend-loading.md`. |
| 17 | + |
| 18 | +Everything below needs only git, Python 3 and the Node toolchain of the repository. |
| 19 | + |
| 20 | +## Pick the mode |
| 21 | + |
| 22 | +| Request | Steps | |
| 23 | +|---|---| |
| 24 | +| **Create** a component | 1. Look for an existing building block: `references/common-components.md`, then `git grep -l <Name> -- opensilex-front/front/src`. 2. Start from `references/component-skeleton.md`, and from `references/list-page.md` for a list page. 3. Write, then run "Verify". | |
| 25 | +| **Modify** a component | Write the new code to the conventions. Do not reformat the whole file unasked, so that the diff stays reviewable: report the remaining deviations (checker output) in the summary. | |
| 26 | +| **Review** a component or a branch | Follow `references/review-checklist.md`: checker, manual grid, report sorted by severity. Report only; fix when asked. | |
| 27 | + |
| 28 | +## Conventions |
| 29 | + |
| 30 | +### File layout |
| 31 | + |
| 32 | +- Blocks in this order: `<template>`, `<script setup lang="ts">`, `<style scoped lang="scss">`. Leave out a |
| 33 | + block that would be empty. |
| 34 | +- In `<script setup>`, after the imports and local types, use these regions with these exact names. The repository |
| 35 | + already has dozens of spellings; a single one keeps IDE folding and the checker's order test working. |
| 36 | + ```ts |
| 37 | + //#region Public |
| 38 | + // defineEmits → defineProps (withDefaults) → defineModel |
| 39 | + //#endregion |
| 40 | + |
| 41 | + //#region Private |
| 42 | + //#region Plugins & services useI18n, useRoute, useStore, inject('$opensilex'), getService |
| 43 | + //#region Template refs |
| 44 | + //#region Data & Computed |
| 45 | + //#region Hooks & watchers |
| 46 | + //#region Event handlers on<Child><Event>(payload: Type) |
| 47 | + //#region Methods |
| 48 | + //#endregion |
| 49 | + |
| 50 | + defineExpose({ … }) |
| 51 | + ``` |
| 52 | + Close every sub-region with its `//#endregion`. A short component can keep only `Public` and `Private`, as long as |
| 53 | + elements of the same kind stay together. |
| 54 | +- **`defineEmits`** uses the named-tuple syntax: `defineEmits<{ toto: [payload: string]; closed: [] }>()`. It is the |
| 55 | + shortest form that types the payload; avoid the call-overload form `(e: 'toto', payload: string): void` and the |
| 56 | + untyped `defineEmits(['toto'])`. Emit only declared events, declare only emitted ones. |
| 57 | +- **Event handlers**: event `foo` of a child `Child` is handled by `onFoo` or `onChildFoo(payload: Type)` in the |
| 58 | + `Event handlers` region, with a typed payload. A one-line handler may stay inline in the template when it reads |
| 59 | + clearly (`@updated="emit('saved', item)"`). When the handler also needs a variable of the template scope, an arrow |
| 60 | + function calls the method: `@changed="(payload) => onNestedChanged(payload, data)"`. |
| 61 | +- **Template refs**: `useTemplateRef<InstanceType<typeof TableAsyncView>>('table')`; for a naive-ui component with an |
| 62 | + instance type, `useTemplateRef<FormInst>('formRef')`. `ref<any>(null)`, `ref(null)` and `useTemplateRef<any>` lose the |
| 63 | + types of the exposed API. |
| 64 | +- **Injection**: `const $opensilex = inject<OpenSilexVuePlugin>('$opensilex')!`, with this name, this key and the `!` |
| 65 | + (the host always provides the plugin). Services: `$opensilex.getService<XService>('opensilex.XService')`, once, at |
| 66 | + `setup` level. |
| 67 | +- A method or variable whose role is not obvious gets a JSDoc comment (`/** … */`). |
| 68 | +- **Key or translated text?** OpenSILEX components that translate by themselves take a **key**: button `label`, `Card`, |
| 69 | + `StringView`, `TableField.label` of `TableAsyncView`, `createTitle` / `editTitle` of `useModalFormLogic`, |
| 70 | + `searchButtonLabelTranslationKey`. `n-*` props, `TableView` and the `placeholder` of `FormSelector` take `t(…)`. Open |
| 71 | + the child component before passing `t(…)` to it: mixing both gives double translations and missing-key warnings. |
| 72 | + |
| 73 | +### Typing: no `any` |
| 74 | + |
| 75 | +The `tsconfig` is lenient (`noImplicitAny: false`, `strictNullChecks: false`) and the build does not check types, so |
| 76 | +nothing stops an `any`: the discipline is manual. |
| 77 | + |
| 78 | +- **DTOs and services**: those of the generated client, as `import type` (`opensilex-core/index`, |
| 79 | + `opensilex-security/index`, `opensilex-core/api/<x>.service`, `opensilex-core/HttpResponse`). |
| 80 | +- **UI types**: those of naive-ui (`DropdownOption`, `DataTableColumns<T>`, `SelectOption`, `TreeSelectOption`, |
| 81 | + `FormRules`, `FormInst`, `DataTableRowKey`). |
| 82 | +- **Store**: `useStore() as OpenSilexStore` (`@/models/Store`). |
| 83 | +- **Local interface** when no existing type matches the handled shape: list filters, `searchMethod` options, an |
| 84 | + aggregated row. |
| 85 | +- **Targeted assertion** only **at the boundary** of a weakly typed shared component (`searchMethod: Function` of |
| 86 | + `TableAsyncView`, `data.item` of a `#cell` slot, the `any` payload of a `select`). It does not spread: the handler's |
| 87 | + parameter carries the precise type, and the rest of the component only sees that type. |
| 88 | + |
| 89 | +### UI: Naive UI, not Bootstrap |
| 90 | + |
| 91 | +- Replace Bootstrap components (grid `row`/`col`, `btn`, `card`, `badge`, `table`, `form-group`, `dropdown`, `modal`, |
| 92 | + `nav-tabs`, `data-bs-*`) with their Naive UI equivalent: `references/bootstrap-to-naive.md`. |
| 93 | +- Leave no Bootstrap class on a naive component (`<n-button-group class="btn-group btn-group-sm">`). Spacing utilities |
| 94 | + (`mb-2`, `p-3`, `d-flex`) are fine. |
| 95 | +- **Import every `n-*`** from `naive-ui` in the component (`import { NCard, NTag } from 'naive-ui'`). Only a few are |
| 96 | + registered globally, in `create({ components: […] })` of `opensilex-front/front/src/main.ts`, and the list differs |
| 97 | + between branches: read it on the current branch before calling an `n-*` global. A tag that is neither imported nor |
| 98 | + global renders nothing, without any error. |
| 99 | + |
| 100 | +### Reuse without modifying |
| 101 | + |
| 102 | +- Search `components/common/` before writing anything: server-side table (`TableAsyncView`), filter panel |
| 103 | + (`SearchFiltersSidebar`), selectors (`FormSelector`, `InfiniteScrollDropdown` and the business selectors built on them), action buttons |
| 104 | + (`CreateButton`, `EditButton`, `DeleteButton`, `DetailButton`), `Card`, `Modal` + `useModalFormLogic`, `*Form` fields. |
| 105 | + Catalogue and API: `references/common-components.md`. |
| 106 | +- **Do not modify these building blocks** unless asked: migrated lists and views depend on them. Report a defect found |
| 107 | + there instead of fixing it on the side. |
| 108 | +- **Open a child component's template before wrapping it.** A selector built on `FormSelector` or `InfiniteScrollDropdown` already renders its label |
| 109 | + and its `n-form-item path`, so it is not wrapped. `*Form` fields (`InputForm`…) go in an `n-form-item path` **without** |
| 110 | + `label`: the field carries the label. Full table in `references/common-components.md`. |
| 111 | +- Use only what a building block **exposes** (`defineExpose`) and actually **emits**. Reading non-exposed internal state |
| 112 | + returns `undefined`, without error. |
| 113 | + |
| 114 | +### Migrated code is an API source, not a style model |
| 115 | + |
| 116 | +The existing code is heterogeneous: many migrated components still use overload emits, `ref<any>(null)` or `any`, and |
| 117 | +few have the `Public` region. Read a migrated component for its **API** (which props, which events), not for its style. |
| 118 | +Shortcuts found in migrated lists, not to be reproduced: |
| 119 | + |
| 120 | +- `:filtersCollapsed="…"` instead of `v-model:filtersCollapsed` on `SearchFiltersSidebar`, so the panel never closes |
| 121 | + after a search; |
| 122 | +- `n-form-item` around `TypeForm` or a selector built on `FormSelector` / `InfiniteScrollDropdown`, plus the CSS hack `:deep(.compact-form-item)` |
| 123 | + to hide the empty label; |
| 124 | +- reading non-exposed `TableAsyncView` state (`onlySelected`, `selectAll`, `totalRow`) and listening to `@refreshed` / |
| 125 | + `@selectall`, which are never emitted; |
| 126 | +- `t(...)` passed to a component that translates by itself (double translation); |
| 127 | +- `class="btn-group btn-group-sm"` on `n-button-group`, `badge badge-pill`, `row` / `col`; |
| 128 | +- `ref<any>(null)`, `useTemplateRef<any>`, `as any`, `null as any`; |
| 129 | +- an `n-*` used without import; |
| 130 | +- filters reset by copying the literal again instead of a `getEmptyFilter()` factory. |
| 131 | + |
| 132 | +Check what is correct instead of copying the neighbouring file. |
| 133 | + |
| 134 | +## Verify |
| 135 | + |
| 136 | +1. **Conventions**, on the touched files: |
| 137 | + ```bash |
| 138 | + python3 .claude/skills/opensilex-vue/scripts/check_vue_conventions.py <files.vue> |
| 139 | + ``` |
| 140 | + Without arguments it checks the `.vue` files changed against `HEAD` and the untracked ones. No `ERROR` may remain in |
| 141 | + the code written; each `WARN` deserves a look. |
| 142 | +2. **Build**, with Node 22, the version pinned in `opensilex-parent/pom.xml` (older versions break the vite/rolldown |
| 143 | + build; check `node --version` first): |
| 144 | + ```bash |
| 145 | + cd opensilex-front/front && npm run build |
| 146 | + ``` |
| 147 | + `vue`, `vite` and `naive-ui` are declared in the **root** `package.json`. If the build fails on |
| 148 | + `Cannot find module 'vite'` or `'naive-ui'`, the dependencies are not installed: say so and suggest `npm install` at |
| 149 | + the root rather than running it without agreement. |
| 150 | +3. **Types: say it plainly.** `npm run build` (`vite build`) does not check types: it strips `import type`, so a wrong |
| 151 | + type path or an `any` gets through. `vue-tsc` is not a project dependency, and |
| 152 | + `opensilex-core/front/types/opensilex-core.d.ts`, referenced by the `tsconfig`, is generated by the Maven build and |
| 153 | + may be missing. Never claim a full type check; write "build OK, type check (vue-tsc) not available in the project". |
| 154 | +4. **Browser**: the user checks the real behaviour (rendering, filters, actions, selection), unless they explicitly ask |
| 155 | + for it to be done here. End by listing what they should look at. |
| 156 | + |
| 157 | +## References |
| 158 | + |
| 159 | +Read only the file the task needs. |
| 160 | + |
| 161 | +- `references/component-skeleton.md`: when creating a component. A complete compliant component on a concrete case, a |
| 162 | + short one, and the modal form pattern. |
| 163 | +- `references/list-page.md`: for a list page. Filter panel, server-side table, row actions, the view that owns the form, |
| 164 | + detail page and tabs. |
| 165 | +- `references/common-components.md`: before using or wrapping a `common/` building block. API, which component renders |
| 166 | + its own label, global naive-ui components, known defects. |
| 167 | +- `references/bootstrap-to-naive.md`: when the markup has Bootstrap classes. |
| 168 | +- `references/review-checklist.md`: for a review. Steps, manual grid, report format. |
| 169 | +- `scripts/check_vue_conventions.py`: run it, no need to read it. Mechanical convention check. |
0 commit comments