Skip to content

Commit 9d06eee

Browse files
Merge branch 'vue3/main' into vue3/yvan/fix-projects
2 parents cfe0081 + 926b6a3 commit 9d06eee

48 files changed

Lines changed: 4631 additions & 679 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.
Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
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.
Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
# Replacing Bootstrap with Naive UI
2+
3+
Every Bootstrap component written in the template, or copied from the old Vue 2 component, is replaced with its Naive
4+
UI equivalent. Two exceptions:
5+
6+
- **a `common/` building block already exists** (action button, `Card`, form `Modal`, `TableAsyncView`): use it, even
7+
if it uses Bootstrap inside;
8+
- **spacing and alignment utilities** (`mb-2`, `me-1`, `p-3`, `d-flex`, `text-muted`…) are fine. For a layout, prefer
9+
`n-space` / `n-flex` anyway.
10+
11+
Reminder: import every component used, `import { NCard, NGrid, NGridItem } from 'naive-ui'`. Only a few are global
12+
(`main.ts`, and the list differs between branches).
13+
14+
| Bootstrap (classes or `data-bs-*`) | Naive UI | Notes |
15+
|---|---|---|
16+
| `container-fluid` / `container` | nothing, or `n-layout-content` | the layout provides the page container |
17+
| `row` + `col-*` / `col-lg-6` | `n-grid` + `n-grid-item` | `:cols="2"` or responsive: `cols="1 m:2"` with `responsive="screen"`; `:x-gap`, `:y-gap` |
18+
| inline alignment (`d-flex gap-2`) | `n-space` / `n-flex` | `n-space vertical` to stack |
19+
| page with a filter panel | `n-layout has-sider` + `SearchFiltersSidebar` + `n-layout-content` | see `list-page.md` |
20+
| `card`, `card-header`, `card-body` | `n-card` | slots `header`, `header-extra`, default, `footer`, `action`. For a detail page, `Card` from `common/` |
21+
| `btn btn-*` | `n-button` | `type="primary" \| "info" \| "success" \| "warning" \| "error"`, `secondary`, `tertiary`, `quaternary`, `ghost`, `size="small"`, `circle`. To create, edit, delete or show details: `CreateButton`, `EditButton`, `DeleteButton`, `DetailButton` |
22+
| `btn-group`, `btn-group-sm` | `n-button-group size="small"` | **without** putting `class="btn-group"` back on it |
23+
| `dropdown`, `dropdown-menu`, `data-bs-toggle="dropdown"` | `n-dropdown` | `:options="DropdownOption[]"`, `@select="(key: string) => …"`, `trigger="click"` |
24+
| `table`, `table-striped` | `n-data-table` | server-side paginated: `TableAsyncView`; small static table: `n-data-table` + `DataTableColumns<T>`; layout table: `n-table` |
25+
| `pagination` | `n-pagination` | not needed with `TableAsyncView`, which includes it |
26+
| `form-group` + `label` + `form-control` | `n-form-item` + `n-input` | or `InputForm` in an `n-form-item path` without `label` (see `common-components.md`) |
27+
| `form-select`, `<select>` | `n-select` | `:options="SelectOption[]"`; for a business resource, the selector built on `FormSelector` or `InfiniteScrollDropdown` |
28+
| `form-check` (checkbox) | `n-checkbox` | `CheckboxForm` in a form |
29+
| `form-check` (radio) | `n-radio-group` + `n-radio` / `n-radio-button` | |
30+
| `form-switch` | `n-switch` | several: `SwitchGroup` |
31+
| `input-group` | `n-input-group` | |
32+
| `badge`, `badge-pill` | `n-tag size="small" round` (label or bare counter); `n-badge :value` (dot on an element) | |
33+
| `alert alert-*` | `n-alert type="info \| success \| warning \| error"` | |
34+
| `nav nav-tabs`, `nav-link` | `n-tabs` + `n-tab-pane` | `type="line"` or `"card"`, `v-model:value` |
35+
| `list-group`, `list-group-item` | `n-list` + `n-list-item` | |
36+
| `collapse`, accordion | `n-collapse` + `n-collapse-item`; `n-collapse-transition` | |
37+
| `modal` (Bootstrap markup) | form: `Modal` from `common/` + `useModalFormLogic`; simple dialog: `n-modal preset="card"` or `preset="dialog"` | |
38+
| confirmation | `DeleteButton` (confirms by itself); otherwise `n-popconfirm` | |
39+
| `data-bs-toggle="tooltip"`, `title` | `n-tooltip` | `trigger` slot |
40+
| `spinner-border` | `n-spin` | around the content: `<n-spin :show="loading">` |
41+
| `progress` | `n-progress` | |
42+
| `toast` | `$opensilex.show*Toast(...)` | do not create a toast |
43+
| `offcanvas` | `n-drawer` + `n-drawer-content` | |
44+
45+
## Example: action menu on the selection
46+
47+
Before (Vue 2 / Bootstrap-Vue):
48+
49+
```html
50+
<div class="btn-group btn-group-sm">
51+
<b-dropdown size="sm" :text="$t('component.common.actions')">
52+
<b-dropdown-item-button @click="clickOnlySelected()">{{ $t('component.common.selected-only') }}</b-dropdown-item-button>
53+
<b-dropdown-item-button @click="resetSelected()">{{ $t('component.common.resetSelected') }}</b-dropdown-item-button>
54+
</b-dropdown>
55+
<span class="badge badge-pill greenThemeColor">{{ selectedCount }}</span>
56+
</div>
57+
```
58+
59+
After:
60+
61+
```vue
62+
<n-space align="center" :size="8">
63+
<n-dropdown trigger="click" :options="actionOptions" @select="onActionsSelect">
64+
<n-button size="small">{{ t('component.common.actions') }}</n-button>
65+
</n-dropdown>
66+
<n-tag size="small" round class="greenThemeColor">{{ selectedCount }}</n-tag>
67+
</n-space>
68+
```
69+
70+
```ts
71+
import { NSpace, NTag, type DropdownOption } from 'naive-ui'
72+
73+
type SelectionAction = 'selected-only' | 'reset-selection'
74+
75+
const actionOptions = computed<DropdownOption[]>(() => [
76+
{ key: 'selected-only' satisfies SelectionAction, label: t('component.common.selected-only') },
77+
{ key: 'reset-selection' satisfies SelectionAction, label: t('component.common.resetSelected') },
78+
])
79+
80+
function onActionsSelect(key: SelectionAction) {
81+
if (key === 'selected-only') tableRef.value?.toggleOnlySelected()
82+
else tableRef.value?.resetSelection()
83+
}
84+
```

0 commit comments

Comments
 (0)