Starseed/.claude/rules/frontend.md

Frontend — Regles Nuxt 4 / Vue 3 / @malio/layer-ui

Base

• TypeScript strict
• 4 espaces d'indentation
• Commentaires (JSDoc, inline, bloc) en francais ; code (variables, types) en anglais
• Chaque module front = un layer Nuxt auto-detecte (frontend/modules/*/nuxt.config.ts minimal)

Appels API

• Toujours useApi() — jamais $fetch, ofetch, axios en direct
• useApi() gere : cookies JWT, erreurs, toasts i18n, parsing Hydra

Stores (Pinia)

• useAuthStore pour l'authentification
• useUiStore pour l'etat UI global (sidebar, modales, etc.)
• Composables avec state singleton (refs module-level) : exposer une fonction reset*() et la rappeler au logout (ex: useSidebar().resetSidebar())

Middlewares globaux

• auth.global.ts protege les routes + charge la sidebar apres login
• modules.global.ts redirige si la route demandee est dans disabledRoutes

i18n et sidebar

• Labels de sidebar = cles i18n sidebar.<module>.*, jamais du texte brut
• Le layout default.vue applique t() sur les labels retournes par /api/sidebar
• Traductions dans frontend/i18n/locales/

Composants formulaires — @malio/layer-ui obligatoire

Tout champ de formulaire / filtre doit utiliser les composants Malio* plutot que <input> / <select> bruts :

• MalioInputText, MalioInputNumber, MalioInputAmount, MalioInputPassword, MalioInputTextArea
• MalioSelect, MalioSelectCheckbox, MalioCheckbox, MalioRadioButton
• MalioInputUpload, MalioTime
• MalioButton, MalioButtonIcon

Exceptions autorisees (commenter un // TODO pour migrer quand la lib couvrira le cas) :

1. Type non couvert : datetime-local, date, color picker, file drag & drop
2. Bug connu bloquant (ex: MalioSelect avec options string) — documenter le bug en commentaire

Toute autre exception requiert validation avant merge.

Tableaux de donnees — MalioDataTable obligatoire

Tout affichage LISTE tabulaire (donnees metier paginees, CRUD admin) doit passer par MalioDataTable :

• Pagination integree
• Slots #header-* pour filtres, #cell-* pour rendu custom
• Pas de <table> brut avec pagination custom

Exception : tableaux purement presentationnels non paginables (diff field/old/new, grille de comparaison, matrice RBAC d'admin, etc.) peuvent rester en <table> HTML brut.

Listes paginees (standard) — usePaginatedList obligatoire

Toute liste qui consomme une GetCollection API doit passer par usePaginatedList (frontend/shared/composables/usePaginatedList.ts). Le composable est le pendant front de la regle ABSOLUE n°13 (« toute collection est paginee cote back ») : il consomme l'envelope Hydra (member / totalItems / view) et expose un etat reactif a brancher directement sur MalioDataTable.

Pattern de reference :

const {
    items,
    totalItems,
    currentPage,
    itemsPerPage,
    itemsPerPageOptions,
    fetch: loadList,
    goToPage,
    setItemsPerPage,
} = usePaginatedList<MyEntity>({ url: '/my-resources' })

onMounted(loadList)

<MalioDataTable
    :columns="columns"
    :items="rows"
    :total-items="totalItems"
    :page="currentPage"
    :per-page="itemsPerPage"
    :per-page-options="itemsPerPageOptions"
    :empty-message="t('foo.empty')"
    @update:page="goToPage"
    @update:per-page="setItemsPerPage"
/>

Garanties offertes par le composable :

• Force Accept: application/ld+json → API Platform 4 renvoie bien member / totalItems (sans Accept, retour tableau plat sans pagination).
• Defaut 10 items/page, choix client 10 / 25 / 50, aligne sur le defaut serveur.
• Mutation setFilters / setSort / setItemsPerPage → retombe systematiquement en page 1.
• Cas limite « page hors borne apres filtre » : retombe automatiquement sur la derniere page valide (tests/usePaginatedList.test.ts).
• Etat 100 % local (refs internes a l'instance) — jamais reflete dans l'URL, conformement a la regle « Etat des tableaux — pas de persistance URL » ci-dessous.

A NE PAS faire :

• Charger une collection complete via ?itemsPerPage=999 pour bypasser la pagination. Le seul cas legitime de retour complet est l'alimentation d'un <select> sur un referentiel ≤ quelques dizaines d'entrees, et il passe par ?pagination=false (echappatoire prevue par pagination_client_enabled: true).
• Reimplementer la pagination prev/next a la main au-dessus de MalioDataTable — le composant porte deja le selecteur items/page et les boutons Prev/Next.
• Persister page/tri/filtre dans la query string — meme regle que pour <MalioDataTable> brut (cf. section suivante).

Etat des tableaux — pas de persistance URL

Interdit de persister l'etat d'un tableau (filtres, pagination, tri par colonne, selection, ligne active, scroll) dans la query string ou de le reinjecter depuis route.query au montage.

• L'etat vit uniquement dans le composant (reactive, ref locales)
• Seuls les deep links "de navigation metier" (ex: ouvrir un detail precis /users/42) sont dans l'URL
• Exceptions autorisees sur demande explicite de l'utilisateur

Interdits

• modules-loader.ts, .module.ts — le scan des layers est automatique
• Hardcode de la sidebar cote front — elle vient de /api/sidebar
• Edition manuelle de extends dans frontend/nuxt.config.ts — les layers sont scannes
• Import d'un module front depuis un autre module — passer par frontend/shared/