maxime.fleury/_Assistant_Lead_Tech

Fork 0

mirror of https://github.com/MaksTinyWorkshop/_Assistant_Lead_Tech synced 2026-04-06 21:41:42 +02:00

Files

MaksTinyWorkshop 2ce7b2955e Purge _ A capitaliser

2026-03-20 13:59:42 +01:00

22 KiB

Raw Blame History

Patterns front-end validés

Ce fichier contient uniquement des patterns front-end :

testés,
validés,
utilisés dans des projets réels (ou des apps complètes, pas des snippets isolés).

Il sert de mémoire durable pour éviter :

de refaire les mêmes erreurs,
de redélibérer éternellement sur des sujets déjà tranchés,
de propager des “bonnes pratiques” théoriques non éprouvées.

Dernière mise à jour : 20-03-2026

Index

Gestion explicite des états UI (loading / empty / error)
Séparation claire server state / client state
Formulaire robuste avec validation et erreurs explicites
Navigation réactive post-action async (React / Expo Router)
Refresh idempotent sur store de liste paginée
UI admin légère sur domaine existant
Intégration tierce en mode link-out — préférer une page locale canonique
Design Tokens natifs TypeScript (Expo / React Native)
Tests de styles React Native sans renderer JSX
Export des styles de composant pour réutilisation partielle
Token typography par usage sémantique (React Native)

Règle d’or

Si ce n’est pas confirmé comme fonctionnel et utile,
ça n’a rien à faire ici.

Pas de conseils vagues
Pas de patterns “à la mode”
Pas de dépendance implicite à un framework ou une version non précisée

Périmètre couvert

SPA et webapps
UX technique (forms, erreurs, loading, feedback)
State management (client / server)
Architecture front-end
Performance et accessibilité
Sécurité front (au niveau applicatif)
DX et maintenabilité

Ce fichier traite le front-end comme un logiciel en production,
au même niveau d’exigence que le backend.

Format standard d’un pattern (obligatoire)

Pattern : <Nom clair et précis>

Objectif : ce que le pattern résout
Contexte : type d’application / contraintes
Quand l’utiliser : cas pertinents
Quand l’éviter : contre-exemples
Avantages : bénéfices concrets
Limites / vigilance : pièges, dette potentielle
Validé le : DD-MM-YYYY
Contexte technique : framework + version + tooling principal

Implémentation (exemple minimal)

(contenu volontairement minimal, lisible, non-magique)

Pattern : Gestion explicite des états UI (loading / empty / error)

Synthèse

Objectif : éviter les interfaces ambiguës ou incohérentes en rendant explicites tous les états possibles d’une vue.
Contexte : SPA ou webapp consommant des données asynchrones (API, backend, cache).
Quand l’utiliser : dès qu’une vue dépend de données externes ou d’un traitement async.
Quand l’éviter : vues purement statiques ou synchrones sans dépendance externe.

Analyse

Avantages :
- UX plus prévisible et compréhensible
- Debug facilité (état visible = problème identifiable)
- Base saine pour tests et accessibilité
Limites / vigilance :
- Peut sembler verbeux sur des écrans simples
- Nécessite une discipline pour ne pas “court-circuiter” les états

Validation

Validé le : 25-01-2026
Contexte technique : SPA (React / Vue / Svelte agnostique), API HTTP

Implémentation (exemple minimal)

if (loading) {
  afficher un skeleton ou spinner
} else if (error) {
  afficher un message clair + action possible
} else if (data est vide) {
  afficher un état empty explicite
} else {
  afficher la vue nominale
}

Checklist

Aucun écran blanc ou silencieux
Message d’erreur compréhensible pour l’utilisateur
États testables individuellement
Accessibilité respectée (focus, lecture écran)
Pas de logique métier cachée dans le rendu

Pattern : Séparation claire server state / client state

Synthèse

Objectif : éviter le mélange des responsabilités entre données serveur et état local UI.
Contexte : SPA ou webapp consommant une API avec interactions utilisateur.
Quand l’utiliser : dès que l’application affiche des données distantes modifiables ou synchronisées.
Quand l’éviter : applications très simples ou purement statiques.

Analyse

Avantages :
- Logique plus lisible et testable
- Réduction des bugs liés aux états incohérents
- Évolutivité facilitée quand l’app grossit
Limites / vigilance :
- Demande de la rigueur dans le découpage
- Peut sembler abstrait au début pour des petits projets

Validation

Validé le : 25-01-2026
Contexte technique : SPA agnostique (React / Vue / Svelte), API HTTP

Implémentation (exemple minimal)

serverState = données venant du backend (fetch, cache, sync)
clientState = état local UI (filtres, onglets, modales, formulaires)

Ne jamais :
- stocker du state UI dans le cache serveur
- dériver la logique UI directement des réponses API sans adaptation

Checklist

Les données serveur peuvent être invalidées / rechargées
L’état UI est local et réinitialisable
Les responsabilités sont lisibles dans le code
Les tests peuvent cibler chaque type d’état
Pas de dépendance implicite entre UI et API

Pattern : Formulaire robuste avec validation et erreurs explicites

Synthèse

Objectif : garantir des formulaires fiables, compréhensibles et maintenables.
Contexte : toute interface avec saisie utilisateur et règles métier.
Quand l’utiliser : dès qu’un formulaire dépasse un simple champ isolé.
Quand l’éviter : formulaires ultra-simples sans validation réelle.

Analyse

Avantages :
- UX claire (l’utilisateur sait quoi corriger)
- Moins d’erreurs silencieuses
- Base saine pour tests et accessibilité
Limites / vigilance :
- Peut sembler verbeux sans discipline
- Risque de duplication si mal factorisé

Validation

Validé le : 25-01-2026
Contexte technique : Front-end agnostique, API HTTP

Implémentation (exemple minimal)

- Validation côté client (format, champs requis)
- Validation côté serveur (règles métier)
- Mapping explicite des erreurs serveur → champs UI
- Aucun submit silencieux

Checklist

Messages d’erreur compréhensibles et localisés
Validation client + serveur cohérente
Focus automatique sur le champ en erreur
États loading / disabled gérés
Tests sur cas valides et invalides

Synthèse

Objectif : déclencher la navigation après une action asynchrone (login, register, submit) de façon idiomatique et sans bypasser la réactivité React.
Contexte : SPA ou app mobile React avec state management (Zustand, Redux, Context) et router déclaratif (React Router, Expo Router, Next.js App Router).
Quand l'utiliser : dès qu'une navigation dépend du résultat d'une action async.
Quand l'éviter : navigations synchrones sans état async impliqué.

Analyse

Avantages :
- Respecte le cycle de vie React (pas de lecture de state hors cycle)
- Re-render automatique si l'état change entre-temps
- Testable : on peut assert sur l'état, pas sur des effets de bord
Limites / vigilance :
- Ne pas oublier les dépendances du useEffect (ESLint react-hooks/exhaustive-deps)
- Gérer le cas "composant démonté" si la navigation peut être annulée

Validation

Validé le : 07-03-2026
Contexte technique : React 18+ / Zustand / Expo Router — pattern applicable sur React Router, Next.js App Router

Implémentation (exemple minimal)

// ❌ Anti-pattern : lecture de state hors cycle React
const handleSubmit = async () => {
  await login(email, password);
  const { accessToken } = useAuthStore.getState(); // bypasse la réactivité
  if (accessToken) router.replace('/(tabs)');
};

// ✅ Pattern correct : useEffect réactif sur le state
const { accessToken, isLoading, error } = useAuthStore();

useEffect(() => {
  if (accessToken && !isLoading && !error) {
    router.replace('/(tabs)');
  }
}, [accessToken, isLoading, error]);

const handleSubmit = async () => {
  await login(email, password);
  // la navigation se déclenche via useEffect quand le store se met à jour
};

Pour les callbacks OAuth (ref nécessaire)

// Quand un callback externe déclenche la navigation
const pendingOAuth = useRef(false);

useEffect(() => {
  if (pendingOAuth.current && accessToken) {
    pendingOAuth.current = false;
    router.replace('/(tabs)');
  }
}, [accessToken]);

const handleOAuth = async () => {
  pendingOAuth.current = true;
  await exchangeWithIdp(token);
};

Checklist

Aucun store.getState() utilisé pour lire l'état post-action dans un handler
useEffect avec dépendances explicites (state pertinent + isLoading + error)
Cas d'erreur géré (ne pas naviguer si error est défini)
useRef si le trigger vient d'un callback externe (OAuth, deep link)
Convention documentée dans la story foundations / project-context avant les premiers écrans

Pattern : Refresh idempotent sur store de liste paginée

Synthèse

Objectif : garantir qu’un pull-to-refresh recharge une liste paginée sans doublons, sans courses réseau et sans état intermédiaire incohérent.
Contexte : app mobile ou SPA avec store de domaine (ex. Zustand) et pagination incrémentale.
Quand l’utiliser : dès qu’une même liste supporte à la fois loadMore et refresh.
Quand l’éviter : listes purement statiques ou données entièrement remplacées sans pagination.

Analyse

Avantages :
- évite les doublons lors des refresh concurrents
- garde une transition atomique entre ancien et nouvel état
- rend le comportement async testable côté store
Limites / vigilance :
- impose une discipline claire entre refresh et loadMore
- demande une clé d’identité stable pour dédupliquer les items

Validation

Validé le : 10-03-2026
Contexte technique : React Native / Expo / Zustand / listes paginées

Implémentation (exemple minimal)

- conserver une promesse de refresh partagée tant qu’un refresh est en vol
- refuser ou réutiliser tout refresh concurrent au lieu d’en lancer un second
- remplacer atomiquement la liste à la fin du refresh
- dédupliquer les items par identifiant au merge des pages suivantes
- empêcher `loadMore` de fusionner sur un snapshot devenu obsolète

Checklist

Une seule promesse de refresh en vol à la fois
refresh et loadMore ont des garde-fous explicites
La liste est remplacée atomiquement après refresh
Les pages suivantes sont dédupliquées par identifiant stable
Tests sur refresh concurrent + refresh suivi de pagination

Pattern : UI admin légère sur domaine existant

Synthèse

Objectif : ajouter une capacité interne simple sans ouvrir trop tôt un back-office séparé ni dupliquer la logique métier.
Contexte : app mobile ou SPA avec un domaine métier déjà structuré et quelques actions internes ponctuelles.
Quand l’utiliser : publication, activation, modération légère, bascule de statut, action opérateur simple.
Quand l’éviter : permissions complexes, workflows multiples, audit riche ou volume d’actions qui justifie un vrai espace d’administration.

Analyse

Avantages :
- réutilise le service et le store métier existants
- limite le coût de structure pour une capacité admin mince
- garde les mutations testables et lisibles
Limites / vigilance :
- ne pas laisser cette approche dériver vers un pseudo back-office implicite
- le refresh après mutation doit être explicite sur les vues impactées

Validation

Validé le : 10-03-2026
Contexte technique : React Native / Expo Router / store de domaine

Implémentation (exemple minimal)

- ajouter une route dédiée minimale pour l’action interne
- réutiliser le service/store métier existant au lieu de créer une couche parallèle
- afficher le statut courant avant action
- bloquer les actions concurrentes avec un flag explicite (`isUpdating*`)
- déclencher un refresh explicite des vues impactées après succès
- éviter les mutations en fire-and-forget

Checklist

Route dédiée minimale, pas de mini back-office générique
Réutilisation du domaine métier existant
Garde-fou explicite contre les doubles actions
Refresh explicite après mutation réussie
Tests sur succès, erreur et action concurrente

Pattern : Intégration tierce en mode link-out — préférer une page locale canonique

Synthèse

Objectif : éviter les parcours concurrents et centraliser les garde-fous UX quand une fonctionnalité publique dépend d’un service tiers externe.
Contexte : site ou webapp avec CTA publics menant vers un tiers de réservation, paiement, prise de rendez-vous ou formulaire externe.
Quand l’utiliser : dès qu’une fonctionnalité externe dispose d’une page locale dédiée côté produit (/reservation, /booking, etc.).
Quand l’éviter : si le produit assume volontairement une sortie directe unique vers le tiers, sans page locale intermédiaire ni besoin de contextualisation.

Analyse

Avantages :
- UX plus cohérente entre home, navigation et pages dédiées
- garde-fous, wording et fallbacks centralisés au même endroit
- facilite l’évolution future vers embed, click-to-load ou variantes de parcours
Limites / vigilance :
- ajoute une étape intermédiaire si la page locale n’apporte aucune valeur
- demande de maintenir l’alignement entre les CTA internes et le parcours canonique

Validation

Validé le : 19-03-2026
Contexte technique : site web public / intégration tierce en mode lien externe

Implémentation (exemple minimal)

- faire pointer les CTA internes (home, nav, landing) vers une page locale dédiée
- faire de cette page locale le point canonique vers le service tiers externe
- centraliser sur cette page le contexte utile, les garde-fous et les fallbacks
- éviter les sorties directes concurrentes vers le tiers depuis plusieurs endroits du site

Checklist

Un parcours canonique unique est défini
Les CTA internes convergent vers la page locale dédiée
Les garde-fous et fallbacks sont centralisés
Les sorties directes concurrentes vers le tiers sont évitées ou justifiées

Pattern : Design Tokens natifs TypeScript (Expo / React Native)

Synthèse

Objectif : centraliser les tokens de design sans librairie externe (NativeBase, Tamagui), typés et barrel-exportés.
Contexte : app Expo / React Native avec un système de design à maintenir.
Quand l’utiliser : dès le début d’un projet mobile, avant les premiers composants.
Quand l’éviter : si une librairie UI opinionée est déjà choisie et gère ses propres tokens.

Analyse

Avantages :
- aucune dépendance externe, zéro configuration magique
- autocomplétion TypeScript exacte via as const + types dérivés
- facile à migrer vers un design system plus élaboré ultérieurement
Limites / vigilance :
- les fichiers TTF doivent être présents dans assets/fonts/ — Google Fonts ne peut pas être téléchargé automatiquement, documenter comme pré-requis dans la story
- ne pas réutiliser les tokens spacing pour les dimensions de composants (voir risques)

Validation

Validé le : 19-03-2026
Contexte technique : Expo SDK 52+ / React Native / TypeScript — app-alexandrie story 0.1

Implémentation (exemple minimal)

// apps/mobile/src/theme/colors.ts
export const colors = {
  primary: ‘#2563EB’,
  error: ‘#DC2626’,
  // ...
} as const;
export type ColorToken = keyof typeof colors;

// apps/mobile/src/theme/spacing.ts
export const spacing = { xs: 4, sm: 8, md: 12, base: 16, lg: 24 } as const;
export type SpacingToken = keyof typeof spacing;

// apps/mobile/src/theme/index.ts (barrel export)
export * from ‘./colors’;
export * from ‘./spacing’;
export * from ‘./typography’;
export * from ‘./shadows’;

Checklist

Tous les tokens as const pour inférence exacte
Pas de Context React — constantes TypeScript pures
Types dérivés (ColorToken = keyof typeof colors) pour l’autocomplétion
useFonts dans _layout.tsx avec guard !fontsLoaded
Fichiers TTF présents dans assets/fonts/ et documentés dans la story

Pattern : Tests de styles React Native sans renderer JSX

Synthèse

Objectif : tester les tokens et styles de composants React Native dans un environnement Jest testEnvironment: node sans renderer JSX.
Contexte : config Jest avec transform: { ‘^.+\\.ts$’: ‘ts-jest’ } — les .tsx ne sont pas transformés.
Quand l’utiliser : tokens de thème, logique pure, valeurs de style exportées.
Quand l’éviter : rendu conditionnel (styles dynamiques inline) — nécessite @testing-library/react-native.

Analyse

Avantages :
- teste que le composant utilise les bons tokens, pas seulement que les tokens ont des valeurs
- détecte les régressions de style sans renderer
- rapide, aucune config Jest supplémentaire
Limites / vigilance :
- ne teste pas le style calculé au runtime (style conditionnel dynamique)

Validation

Validé le : 19-03-2026
Contexte technique : React Native / Jest / ts-jest — app-alexandrie story 0.2

Implémentation

// Button.tsx — exporter le StyleSheet avec un nom préfixé
export const buttonStyles = StyleSheet.create({
  base: { borderRadius: 20, height: 57 },
  primary: { backgroundColor: colors.primary },
});
export function Button(...) { ... }

// ui-components.spec.ts — importer et vérifier les tokens
import { buttonStyles } from ‘./Button’;
import { colors } from ‘@/theme’;

it(‘variante primary utilise colors.primary’, () => {
  expect(buttonStyles.primary.backgroundColor).toBe(colors.primary);
});

Deux niveaux de tests UI recommandés

.spec.ts (node) : tokens, valeurs, logique pure
.spec.tsx (config séparée avec renderer) : rendu visuel, interactions

Pattern : Export des styles de composant pour réutilisation partielle (React Native)

Synthèse

Objectif : partager les dimensions et formes d’un composant UI vers des éléments custom qui en dérivent, sans dupliquer les valeurs.
Contexte : app React Native où des screens construisent des éléments qui doivent être "au gabarit" d’un composant existant.
Quand l’utiliser : bouton custom OAuth, container calqué sur un composant de base, etc.
Quand l’éviter : si l’écart visuel est intentionnel — dans ce cas, une constante locale est plus claire.

Analyse

Avantages :
- zéro drift silencieux : si les dimensions du composant changent, tous les éléments dérivés suivent
- tests de styles possibles en dehors du composant
Limites / vigilance :
- à n’utiliser que pour des éléments vraiment dérivés, pas comme contournement de design system

Validation

Validé le : 19-03-2026
Contexte technique : React Native / StyleSheet — app-alexandrie story 0.3

Implémentation

// Button.tsx
export const buttonStyles = StyleSheet.create({
  base: { borderRadius: 20, height: 57 },
  primary: { backgroundColor: colors.primary },
});
export function Button(...) { ... }

// login.tsx — bouton OAuth au gabarit du Button
import { buttonStyles } from ‘@/components/ui/Button’;
<TouchableOpacity style={[buttonStyles.base, styles.facebookButton]} />

Pattern : Token typography par usage sémantique (React Native)

Synthèse

Objectif : éviter les mauvais usages de tokens typography visuellement proches mais sémantiquement distincts.
Contexte : fichier typography.ts dans un design system React Native.
Quand l’utiliser : dès que deux tokens partagent la même taille mais un poids différent.
Quand l’éviter : jamais — les tokens typography doivent toujours refléter l’usage, pas l’apparence.

Analyse

Avantages :
- prévient les "approximations" de tokens en code review
- changement de style d’usage spécifique sans régression globale
Limites / vigilance :
- en review : chercher les usages sans fontWeight explicite — c’est souvent le signe que le mauvais token a été choisi

Validation

Validé le : 19-03-2026
Contexte technique : React Native / TypeScript — app-alexandrie story 0.4

Implémentation

// Bon : nommé par usage sémantique
listItemTitle: { fontSize: 12, fontWeight: ‘600’ },  // titre d’un item de liste
caption: { fontSize: 12, fontWeight: ‘500’ },         // info secondaire, hints

// Mauvais : nommé par apparence
mediumText12: { fontSize: 12, fontWeight: ‘500’ },    // ambigu, réutilisé à tort

Règle : caption (Medium) ≠ listItemTitle (SemiBold) même si la taille est identique. Ne jamais piocher un token "par approximation".

Principes transverses

Un pattern = une responsabilité claire
On privilégie la simplicité locale avant la généricité globale
Le code doit rester compréhensible 6 mois plus tard
Si un pattern devient central → il mérite une décision d’architecture dédiée

⸻

Notes importantes

3 bons patterns > 30 moyens
Si un pattern évolue :
- on met à jour la date
- on précise le nouveau contexte
- En cas de doute → le pattern n’entre pas encore ici

22 KiB Raw Blame History Unescape Escape

Patterns front-end validés

Index

Règle d’or

Périmètre couvert

Format standard d’un pattern (obligatoire)

Pattern : <Nom clair et précis>

Implémentation (exemple minimal)

Pattern : Gestion explicite des états UI (loading / empty / error)

Synthèse

Analyse

Validation

Implémentation (exemple minimal)

Checklist

Pattern : Séparation claire server state / client state

Synthèse

Analyse

Validation

Implémentation (exemple minimal)

Checklist

Pattern : Formulaire robuste avec validation et erreurs explicites

Synthèse

Analyse

Validation

Implémentation (exemple minimal)

Checklist

Pattern : Navigation réactive post-action async (React / Expo Router)

Synthèse

Analyse

Validation

Implémentation (exemple minimal)

Pour les callbacks OAuth (ref nécessaire)

Checklist

Pattern : Refresh idempotent sur store de liste paginée

Synthèse

Analyse

Validation

Implémentation (exemple minimal)

Checklist

Pattern : UI admin légère sur domaine existant

Synthèse

Analyse

Validation

Implémentation (exemple minimal)

Checklist

Pattern : Intégration tierce en mode link-out — préférer une page locale canonique

Synthèse

Analyse

Validation

Implémentation (exemple minimal)

Checklist

Pattern : Design Tokens natifs TypeScript (Expo / React Native)

Synthèse

Analyse

Validation

Implémentation (exemple minimal)

Checklist

Pattern : Tests de styles React Native sans renderer JSX

Synthèse

Analyse

Validation

Implémentation

Deux niveaux de tests UI recommandés

Pattern : Export des styles de composant pour réutilisation partielle (React Native)

Synthèse

Analyse

Validation

Implémentation

Pattern : Token typography par usage sémantique (React Native)

Synthèse

Analyse

Validation

Implémentation

Principes transverses

Notes importantes

22 KiB

Raw Blame History