Sasedev/pgr
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

0.1.1-alpha.5

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-09-27 11:43:09 +02:00
parent 89b8ea88c1
commit 55c6f7b05d
12 changed files with 885 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files

143
docs/skeletons/003-WEB_FRONTEND.md Normal file
View File

@@ -0,0 +1,143 @@
<!-- file: docs/skeletons/003-WEB_FRONTEND.md -->
<!-- version: 1 -->
# Skeleton — Web frontend
## Objectif
Cette specification décrit une specialization composable pour créer une baseline frontend Web contrôlée sans confondre langage, package ecosystem, build tool, styles et host.
Elle se compose avec [`001-PROJECT_GOVERNANCE_FOUNDATION.md`](001-PROJECT_GOVERNANCE_FOUNDATION.md), sélectionne les owners Web réellement applicables de la famille `500` et utilise les templates/guides `008`, `009` et `010` lorsqu'ils correspondent aux choix du projet.
Le contrat transversal des skeletons reste possédé par [`../rules/220-SKELETONS.md`](../rules/220-SKELETONS.md).
## Applicabilité
Appliquer cette specialization lorsqu'un projet ou sous-projet possède un frontend Web autonome ou embarqué dont la baseline frontend est contrôlée par le projet.
Elle peut servir de fondation frontend à un host plus spécifique, par exemple Tauri, sans rendre ce host applicable par elle-même.
Pour un projet existant, cette specification sert de référence de comparaison : l'adoption suit [`../rules/230-ADOPTION.md`](../rules/230-ADOPTION.md) et classe les choix existants `ADOPT / KEEP-LOCAL / OVERRIDE / DEFER` plutôt que de réécrire son layout.
Ne pas appliquer ce skeleton à un backend sans frontend, à une page statique qui n'a besoin d'aucune de ces responsabilités, ni uniquement parce que Vite/TypeScript sont recommandés ailleurs.
## Owners sélectionnables
La composition de référence d'un frontend moderne contrôlé est :
```text
GENERAL
+ 500 language / ecosystem family
+ 530 TypeScript
+ 540 JavaScript package ecosystem
+ 550 Vite
+ 560 CSS / Sass
```
La sélection reste factuelle :
- `530` est sélectionné lorsque TypeScript est utilisé ; TypeScript **SHOULD** être préféré pour une baseline durable lorsqu'il est compatible avec le besoin ;
- `540` est sélectionné lorsqu'un `package.json`, un package manager ou des dépendances JavaScript sont réellement utilisés ;
- `550` est sélectionné uniquement si Vite est choisi ; Vite **SHOULD** être préféré pour les frontends compatibles, sans être obligatoire ;
- `560` est sélectionné si le frontend possède une chaîne CSS/Sass ; CSS seul reste valide et Sass reste optionnel, bien que recommandé pour une chaîne non triviale ou un package exposant une API Sass utile.
Le skeleton ne transforme pas une recommandation `SHOULD` en `MUST`.
## Fondation et fichiers de départ
Lorsque TypeScript + package ecosystem sont sélectionnés, le projet MAY partir des templates :
```text
templates/web-typescript/package.json
templates/web-typescript/tsconfig.json
```
Le guide [`../templates/008-WEB_TYPESCRIPT_PACKAGE.md`](../templates/008-WEB_TYPESCRIPT_PACKAGE.md) possède leur adaptation.
PGR ne fournit pas de `vite.config.ts` universel. Si Vite est sélectionné, créer ou adapter la configuration réelle à partir des décisions décrites dans [`../templates/009-WEB_VITE.md`](../templates/009-WEB_VITE.md).
PGR ne fournit pas non plus de `main.scss` ou de thème universel. Si CSS/Sass est sélectionné, organiser les sources selon les besoins réels et suivre [`../templates/010-WEB_CSS_SASS.md`](../templates/010-WEB_CSS_SASS.md).
Le nom `frontend/` est une convention possible, pas un chemin imposé par ce skeleton.
## Décisions destinataire avant matérialisation
Résoudre explicitement au minimum :
1. la racine et le scope exacts du frontend ;
2. TypeScript ou JavaScript, avec justification si une nouvelle baseline durable n'adopte pas la recommandation TypeScript ;
3. le package manager réel et la politique de lockfile adaptée au rôle du package ;
4. les versions réelles de TypeScript et des dépendances, ainsi que les déclarations `@types/*` réellement nécessaires ;
5. Vite ou un build tool alternatif, avec ses chemins `root`, cache, outputs, `base`, ports, plugins et assets lorsqu'ils s'appliquent ;
6. CSS seul ou Sass, puis l'implémentation Sass réelle si sélectionnée ;
7. le framework CSS éventuel : aucun, Bootstrap, Tailwind CSS ou autre ; ce choix reste local au projet ;
8. les entrypoints de styles publics des dépendances et les overrides réellement nécessaires ;
9. les scripts de package réellement utiles (`typecheck`, `dev`, `build`, `preview` ou équivalents) ;
10. la gate frontend indépendante du host et les éventuels smokes navigateur utiles ;
11. les prérequis produits par d'autres owners, s'il en existe, sans les faire absorber par le frontend.
Aucune décision ouverte ne doit être remplacée silencieusement par une valeur observée dans Games ou KSP.
## Dépendances et manifest
Le package réel **SHOULD** rester privé lorsqu'il représente une application non publiée, conformément à `540`.
Les dépendances de développement telles que TypeScript, Vite, Sass ou packages de déclarations sont ajoutées uniquement si les choix du projet les rendent nécessaires. Le skeleton MUST NOT préremplir `@types/node`, `@types/bootstrap`, `sass-embedded`, Vite ou Bootstrap sans besoin réel ni version décidée.
Lorsqu'une dépendance fournit déjà ses propres types, ne pas ajouter un package `@types/*` redondant.
## Styles
CSS source et Sass source sont des entrées versionnées. Les CSS compilées/minifiées, sourcemaps et copies dans l'output sont générées sauf contrat de distribution explicite.
Pour du nouveau Sass contrôlé, `@use` / `@forward` sont préférés lorsque les dépendances le permettent. Une compatibilité `@import` peut être conservée pour un package existant qui l'exige encore.
Le choix d'un framework CSS ne rend ni Bootstrap, ni Tailwind CSS, ni un thème spécifique normatif pour les autres projets.
## Build et outputs
Lorsque Vite est sélectionné, le cache et `build.outDir` restent générés et hors Git. Les chemins exacts restent locaux.
`build.emptyOutDir = true` n'est utilisé que sur un output dédié. `vite preview` reste un smoke/prévisualisation locale et ne devient pas un serveur de production.
Un autre build tool possède ses propres décisions project-specific tant qu'aucun owner PGR dédié n'existe.
## Validation initiale
La validation suit [`../validation/005-WEB_FRONTEND_VALIDATION.md`](../validation/005-WEB_FRONTEND_VALIDATION.md).
Selon les profils sélectionnés, elle doit pouvoir prouver indépendamment du host, autant que possible :
```text
restore reproductible
TypeScript typecheck
compilation/transformation des styles
build frontend de production
smoke navigateur seulement si nécessaire
```
La commande concrète appartient au package manager et aux outils réellement sélectionnés.
Le host reçoit ensuite sa propre gate d'intégration. Un PASS frontend ne constitue pas un PASS Tauri ou plateforme.
Une instanciation temporaire MAY être utilisée pour un dry-run de cette specialization. Elle doit employer les toolchains officielles réelles plutôt qu'un audit Python simulant TypeScript/Vite/Sass.
## Composition avec un host
Un host peut composer ce skeleton comme fondation frontend, puis ajouter son propre profil/skeleton.
Cette composition ne transfère jamais au host l'ownership de TypeScript, du package manager, de Vite ou de Sass/CSS.
Le skeleton Tauri reste `DEFER` pendant `0.1.1`. La présence du présent skeleton Web satisfait une pièce de préparation mais ne décide pas à elle seule la promotion du candidat Tauri.
## Hors scope
Cette specification ne possède pas :
- Tauri ou un autre host natif ;
- WASM ou ses bindings/générations ;
- backend/serveur Web ;
- deployment/operations ;
- choix de framework UI/CSS universel ;
- configuration de sécurité propre à un host ;
- service worker/PWA tant qu'un owner distinct n'est pas justifié.