docs(knowledge): capitalisation frontend — intégration du triage local (mai-juin 2026)

Triage et intégration des propositions frontend du buffer 95_a_capitaliser.md
(lot local RL799_V2/Vue3 + app-alexandrie/RN-Expo, mai-juin 2026).

~73 entrées intégrées sur knowledge/frontend/ + 1 nouveau fichier, dont :
- patterns/state.md : race-token partagé latest-wins (fusion 3 props), capture sync anti-race,
  event bus timestamp, clé cache composite, état dérivé = computed
- risques/state.md : 9 risques Zustand/store (fetchId reset, useRef remount, re-fetch infini
  sur [], flag optimiste écrasé, cache détail/liste stale, latch sans reset, :key index)
- patterns/navigation.md : Expo Router (tab bar, useFocusEffect, Href typé, routing pur fusionné)
- patterns/general.md : helpers temps purs, composants génériques + skeleton, fail-fast, touch target
- risques/general.md : 24 risques (sweep statique, filtre client liste paginée, hooks avant return,
  a11y VoiceOver/disabled, redirection allowlist, RangeError toISOString, section i18n...)
- design-tokens (cluster theming light/dark MD3), tests, performance, react-native, nextjs
- NOUVEAU risques/responsive.md (gating par capacité d'input + checklist régressions mobile)
- READMEs patterns/risques mis à jour

Doublons inter-fichiers évités (vérifié : aucune ancre dupliquée introduite).
Rejets (doublons 91/9/87), reciblages workflow (156/257) et bloc 32 (CLAUDE projet) non intégrés ici.
Source 95_a_capitaliser.md non purgée (purge en fin de capitalisation complète).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
MaksTinyWorkshop
2026-06-25 15:31:53 +02:00
parent f1b783407a
commit 5f5c87296e
15 changed files with 2439 additions and 12 deletions
+368
View File
@@ -375,3 +375,371 @@ Sur un écran qui mélange actions constructives et destructives (ex : saisie in
- Hint général qui répète ce que l'empty state dit déjà → 1 message, 1 niveau d'info
- Confondre "titre de page" (l'onglet actif suffit souvent) et "structure de section" (eyebrows)
- Action destructive en variant primary or → danger explicite
---
<a id="pattern-reset-defensif-pointer-events"></a>
## Pattern : Reset défensif du state pointer events au `pointerdown`
### Synthèse
- **Objectif** : éviter qu'un composant swipe/drag reste figé dans un état corrompu (`dragging = true`) quand un `pointerup` est "volé" par une modale ou une navigation post-action.
- **Contexte** : composant gérant `@pointerdown / @pointermove / @pointerup` qui émet une action ouvrant une modale au `pointerup` (la modale prend le focus → le pointer quitte la card → `pointerup` ne remonte jamais).
- **Quand l'utiliser** : tout composant à geste pointer émettant une action qui change de surface (modale, nav).
- **Quand l'éviter** : geste pur sans effet de bord de navigation.
### Analyse
- **Avantages** : robuste face aux modales/navigations/focus switches ; un seul point d'entrée à protéger ; pas de logique conditionnelle complexe.
- **Limites / vigilance** : ne couvre pas le démontage du composant pendant le drag (géré par le cycle de vie Vue). Pattern complémentaire : flag anti-click synthétique pour ne pas déclencher un `@click` natif après le geste.
### Validation
- Validé le : 05-05-2026
- Contexte technique : Vue 3 / pointer events — RL799 (`ProfaneListCard`)
### Implémentation
```typescript
const handlePointerDown = (event: PointerEvent) => {
if (event.pointerType === 'mouse' && event.button !== 0) return;
resetSwipe(); // défense en profondeur : un pointerup précédent a pu être "volé"
activePointerId.value = event.pointerId;
// …
};
// flag anti-click synthétique : posé en pointerup, consommé dans @click
const handleClick = (): void => {
if (swipeJustHandled.value) { swipeJustHandled.value = false; return; }
emit('select');
};
```
---
<a id="pattern-modale-dediee-vs-partagee"></a>
## Pattern : Modale dédiée vs partagée — décider à la 2ᵉ contrainte
### Synthèse
- **Objectif** : décider en amont s'il faut étendre une modale partagée (`v-if`/`forcedType`/`mode`) ou créer une modale dédiée quand un type métier se décline en variantes aux contraintes d'édition différentes.
- **Contexte** : type métier (Document) décliné en variantes (planche, helper) avec champs obligatoires/validations/types autorisés divergents.
- **Quand l'utiliser** : dès qu'une variante diverge d'un cas standard.
- **Quand l'éviter** : variantes ne différant que par le wording (préférer alors la factorisation par mode).
### Analyse
- **Critère de décision** : modale **dédiée dès que ≥ 2 contraintes divergent** (type figé vs éditable, champ exclusif, champs masqués, validation conditionnelle). 1 seule contrainte → prop conditionnelle sur la modale partagée.
- **Avantages dédiée** : impossible de corrompre la catégorie (type figé en TS, jamais dans le patch) ; pas d'explosion combinatoire de `v-if`.
- **Limites / vigilance** :
- une modale partagée avec select à fallback peut **silencieusement** basculer une ressource d'une catégorie à l'autre (cas vécu : `TYPE_OPTIONS` sans `'helpers'` → fallback `'planches'` au save)
- duplication ~80 % (a11y, focus trap, layout) : extraire un composable partagé pour le focus trap si identique, classes BEM dédiées sinon
- **Détection en revue** : `grep "forcedType\|forcedMode\|isVariantX"` dans une modale partagée — si > 3 occurrences, refactorer en modale dédiée.
### Validation
- Validé le : 06-05-2026
- Contexte technique : Vue 3 — RL799 (`DocumentEditModal``HelperEditModal`/`HelperUploadModal`)
---
<a id="pattern-fail-fast-branche-unreachable-dev"></a>
## Pattern : Fail-fast sur branche unreachable en `__DEV__`
### Synthèse
- **Objectif** : éviter qu'un `return;` no-op silencieux sur une branche unreachable (garantie par un early-return en amont) ne devienne un bug fantôme si un refactor casse l'invariant.
- **Contexte** : `switch`/`match` dont un case est inatteignable par construction (ex. CTA paywall jamais atteint car `SUBSCRIPTION_REQUIRED` fait un early-return avant le rendu).
- **Quand l'utiliser** : toute branche unreachable par invariant.
- **Quand l'éviter** : branche réellement atteignable (gérer le cas normalement).
### Analyse
- **Avantages** : tout refactor cassant l'invariant fait crasher l'app en dev (feedback immédiat) ; la prod reste safe (`return;` no-op) ; le commentaire documente l'invariant et la story.
- **Limites / vigilance** : anti-pattern `// no-op pour l'instant (cas marginal)` sans throw — le cas marginal devient un bug silencieux le jour où il se réalise.
### Validation
- Validé le : 29-05-2026
- Contexte technique : React Native — app-alexandrie (ux-cleanup-7, CTA "Débloquer ce pack")
### Implémentation
```typescript
switch (model.action) {
case 'paywall':
if (__DEV__) throw new Error('[story-X] CTA paywall atteint — invariant cassé ?');
return; // prod : no-op safe
// …
}
```
---
<a id="pattern-extension-retrocompatible-composant"></a>
## Pattern : Extension rétrocompatible d'un composant vs création d'un sibling
### Synthèse
- **Objectif** : étendre un composant existant via une prop optionnelle plutôt que créer un sibling quasi-dupliqué, quand le composant convient à ~80 % d'un nouveau use-case.
- **Contexte** : composant UI (ex. FAB circulaire icon-only) à étendre pour un nouveau cas (porter un label).
- **Quand l'utiliser** : quand 4 critères tiennent (voir Analyse).
- **Quand l'éviter** : logique métier divergente, ou props mutuellement exclusives qui s'accumulent (signal de 2 composants déguisés).
### Analyse
- **Critères pour étendre** : (1) la partie variante (label, icon, taille) ≠ la partie invariante (positionnement, ombre, animation, a11y) ; (2) l'invariant DOIT rester partagé (un seul fichier à toucher quand la nav change) ; (3) la prop d'extension est optionnelle avec un défaut préservant le comportement actuel ; (4) pas de logique métier divergente.
- **Avantages** : 1 fichier, 1 batch de tests, call-sites existants intacts (0 régression).
- **Limites / vigilance** : si le rendu fait `if (mode === 'X') … else …` plus de 2-3 fois → deux composants déguisés, séparer. Anti-pattern : `Fab.tsx` + `FabExtended.tsx` avec ~80 % de styles dupliqués (un bug de positionnement se corrige dans un seul fichier et ressurgit sur l'autre écran).
### Validation
- Validé le : 29-05-2026
- Contexte technique : React Native — app-alexandrie (FAB partagé Messages/Contenu/Forum)
### Implémentation
```typescript
type FabProps = {
icon: MaterialIconName;
onPress: () => void;
accessibilityLabel: string;
label?: string; // optionnel → bascule en mode extended si présent
bottomOffset?: number;
};
const isExtended = typeof label === 'string' && label.length > 0;
// call-site existant inchangé : <Fab icon="add" onPress={...} accessibilityLabel="Nouveau message" />
```
---
<a id="pattern-cta-toggle-async-preserver-etat"></a>
## Pattern : CTA toggle async — préserver l'état pendant le loading
### Synthèse
- **Objectif** : garder visible l'indicateur de l'état pré-toggle (ex. icône check "Suivi") pendant le chargement async, pour ne pas perdre le repère visuel.
- **Contexte** : bouton toggle d'état (Suivre/Suivi, like/unlike) avec action async.
- **Quand l'utiliser** : tout CTA toggle dont l'action est asynchrone.
- **Quand l'éviter** : action synchrone instantanée.
### Analyse
- **Règle** : ne pas remplacer la **totalité** de l'état visible par un spinner — garder au moins un indicateur de l'état pré-toggle pour la durée du loading.
### Validation
- Validé le : 29-05-2026
- Contexte technique : React Native — app-alexandrie (`directory-follow-button.tsx`, ux-cleanup-9)
### Implémentation
```tsx
// ✅ l'icône check reste visible, hors du ternaire isLoading
<View style={containerStyle}>
{isFollowing && <Icon name="check" />}
{isLoading ? <Spinner /> : <Label>{label}</Label>}
</View>
```
---
<a id="pattern-helpers-fail-safe-data-backend"></a>
## Pattern : Helpers fail-safe face aux bugs data backend
### Synthèse
- **Objectif** : qu'un helper de transformation donnée → affichage traite les cas dégénérés (date future, 0, NaN, format invalide) avec un comportement neutre, sans amplifier le bug visuellement.
- **Contexte** : helpers de formatage/dérivation consommant une donnée backend potentiellement bugguée.
- **Quand l'utiliser** : tout helper qui mappe une donnée externe vers de l'UI.
- **Quand l'éviter** : donnée 100 % maîtrisée localement.
### Analyse
- **Anti-patterns** : `createdAt` futur → "tout récent" → tous les contenus affichent "Nouveau" (cascade) ; `duration === 0` → "moins d'1 min" trompeur.
- **Règle** : retour neutre (`false` / `''` / `'—'`) + `console.warn` en `__DEV__` pour remonter la régression API sans polluer la prod.
### Validation
- Validé le : 30-05-2026
- Contexte technique : React Native — app-alexandrie (ux-cleanup-15, `isContentRecent`/`formatDuration`)
### Implémentation
```ts
export function isContentRecent(createdAt, now = new Date()) {
if (!createdAt) return false;
const created = parse(createdAt);
if (Number.isNaN(created.getTime())) return false;
const ageMs = now.getTime() - created.getTime();
if (ageMs < 0) {
if (__DEV__) console.warn('[isContentRecent] createdAt futur:', createdAt);
return false; // neutre, n'amplifie pas le bug
}
return ageMs < THRESHOLD;
}
```
---
<a id="pattern-props-raccourci-composant-generique"></a>
## Pattern : Prop de raccourci pour composant générique
### Synthèse
- **Objectif** : éviter qu'un cas d'usage dominant ne force chaque callsite à un wrapper répétitif, en ajoutant une prop de raccourci.
- **Contexte** : composant générique (`<EmptyState>`) appelé partout avec le même wrapper (`icon={<ThemedText style={{fontSize:48}}>📭</ThemedText>}`).
- **Quand l'utiliser** : wrapper identique répété sur plusieurs callsites.
- **Quand l'éviter** : variété réelle de wrappers (garder la prop générique seule).
### Analyse
- **Règle** : la prop générique (`icon?: ReactNode`) reste prioritaire pour les cas custom ; la prop raccourci (`emoji?: string`) injecte un wrapper standard.
- **Garde-fou** : 1-2 props de raccourci max. Si le cas devient complexe, exposer un sous-composant (`<EmptyState.Emoji>`) ou refactorer.
### Validation
- Validé le : 30-05-2026
- Contexte technique : React Native — app-alexandrie (`EmptyState`, ux-cleanup-15)
---
<a id="pattern-compositions-semantiques-utilisees"></a>
## Pattern : Compositions sémantiques — la migration doit les utiliser
### Synthèse
- **Objectif** : éviter de définir des compositions sémantiques (`typography.body`, `colors.actionPrimary`) que la migration n'utilise pas, laissant les tokens atomiques s'imposer et le sémantique devenir du code mort.
- **Contexte** : migration vers un design system avec compositions + tokens atomiques.
- **Quand l'utiliser** : toute migration introduisant des compositions sémantiques.
### Analyse
- **Règle** : la migration trie — composition existante pour le besoin → l'utiliser ; sinon token atomique + signaler en review qu'une composition pourrait être créée.
- **Ratio cible** : > 50 % d'usages de compositions. Si < 30 %, soit elles sont mal nommées, soit à supprimer (sur-engineering).
### Validation
- Validé le : 29-05-2026
- Contexte technique : React Native — app-alexandrie (ux-cleanup-12/13)
---
<a id="pattern-touch-target-44-minwidth-minheight"></a>
## Pattern : Touch target 44pt — imposer `minWidth` ET `minHeight`
### Synthèse
- **Objectif** : garantir une zone tap 44×44 (HIG iOS), pas 44×N — `minHeight: 44` seul laisse la largeur < 44 sur un label court.
- **Contexte** : composants génériques (`<EmptyState ctaButton>`, `<Button>`) où le caller fournit le label.
- **Quand l'utiliser** : tout CTA dont le label peut être court ("OK", "Annuler", chip).
- **Quand l'éviter** : zone tap déjà large par construction.
### Analyse
- **Cas d'oubli typique** : CTA court → label étroit + padding insuffisant → zone < 44 en width malgré `minHeight: 44` (miss-tap fréquent sur iPhone SE / gants).
- **Trade-off** : `minWidth: 44` est un floor invisible, rarement contraignant pour des labels longs.
### Validation
- Validé le : 31-05-2026
- Contexte technique : React Native — app-alexandrie (ux-cleanup-14)
### Implémentation
```tsx
ctaButton: { minHeight: 44, minWidth: 44, justifyContent: 'center', alignItems: 'center' }
```
---
<a id="pattern-helpers-temps-date-purs"></a>
## Pattern : Helpers temps/date purs centralisés (formatage relatif, groupement)
### Synthèse
- **Objectif** : centraliser le formatage temporel (date relative, groupement par blocs) dans des helpers purs testables env node, pour éviter la divergence de wording entre écrans et entre projets.
- **Contexte** : écrans multiples affichant des dates (Notifications, Messages, Feed) ou un timeline de messages séquencés (chat, commentaires).
- **Quand l'utiliser** : dès que > 1 écran formate des dates relatives, ou qu'une liste temporelle sature de timestamps.
- **Quand l'éviter** : un seul affichage de date trivial.
### Analyse
- **Avantages** : helper pur, `now` injectable → tests déterministes ; 0 dépendance lib (Intl natif, -50 Ko vs date-fns/dayjs) ; le 1er dev d'une story partagée écrit le helper, les suivants consomment.
- **Décisions structurantes** :
- bornes "hier"/jours semaine = **jours calendaires** (`startOfDay(now) startOfDay(date)`), pas deltas en ms (sinon 24h pile ≠ perception humaine)
- pas de "dans N min" pour une date future (clock skew) → retomber sur "à l'instant"
- tolérance gracieuse : `string` ISO invalide → fallback, jamais de crash
- groupement chat : séparateur centré quand delta > 5 min OU changement de jour ; 1er message toujours précédé d'un séparateur ; la fonction attend l'ordre **croissant**, le caller reverse si liste `inverted` (ne pas coupler la logique à l'index FlatList)
### Validation
- Validé le : 29-05-2026
- Contexte technique : React Native — app-alexandrie (`relative-time.ts`, `timestamp-grouping.ts`, ux-cleanup-10/11)
### API
```ts
formatRelativeTime(input: Date | string, now: Date = new Date()): string
// → "à l'instant" / "il y a N min" / "il y a N h" / "hier" / "lun" / "12 mars" / "12 mars 2025"
groupMessagesByTime<T>(messages: T[], now?: Date): GroupedItem<T>[]
// GroupedItem = { kind: 'timestamp' | 'message'; ... }
```
---
<a id="pattern-avatar-initiale-pastel-deterministe"></a>
## Pattern : Avatar circulaire avec initiale pastel déterministe
### Synthèse
- **Objectif** : différencier visuellement des utilisateurs sans photo (early adopters, B2B interne) via une initiale colorée déterministe.
- **Contexte** : listes d'utilisateurs où les photos de profil sont rares.
- **Quand l'utiliser** : ~quelques centaines d'utilisateurs, photos optionnelles.
- **Quand l'éviter** : photos systématiques, ou besoin d'unicité forte (collisions visuelles assumées ici).
### Analyse
- **Implémentation** : palette ~7 couleurs mappées sur tokens design system + 1 fallback grisé ; hash trivial (somme charCodes du nom trimmé modulo `palette.length - 1`) ; 1ère lettre majuscule (préserver accents) ; `null`/vide → fallback "?" grisé.
- **Avantages** : 0 dépendance, testable env node, suit light/dark, déterministe (un nom = toujours la même couleur).
- **Anti-patterns** : couleur aléatoire au mount (casse la reconnaissance) ; hash sur UUID (opaque, change au renommage — hasher le nom affiché) ; lib crypto pour le hash (surdimensionné).
### Validation
- Validé le : 29-05-2026
- Contexte technique : React Native — app-alexandrie (`avatar-initial.tsx`, ux-cleanup-11)
### API
```ts
<AvatarInitial name={"charlie" | null} size={40} />
```
---
<a id="pattern-composants-generiques-etats-chargement"></a>
## Pattern : Composants UI génériques + états de chargement (EmptyState, Skeleton)
### Synthèse
- **Objectif** : factoriser le layout des écrans liste (vide / chargement) dans des composants génériques tout en laissant le wording au caller pour respecter la voix produit.
- **Contexte** : N écrans liste partageant un layout d'état vide et un skeleton de premier chargement.
- **Quand l'utiliser** : ≥ 2 écrans liste avec états vide/chargement similaires.
- **Quand l'éviter** : écran unique sans réutilisation.
### Analyse
- **`<EmptyState>`** : API `{ icon?, emoji?, title, description?, cta? }`. Le caller fournit le wording (calme, bienveillant, non alarmiste) et un CTA **contextuel uniquement quand utile** (pas de "Voir tout" sur une liste vide qui ne pointe nulle part).
- **`<SkeletonScreen>`** : API `{ variant: 'card'|'list-item'|'text-line'|'header', count }`, shimmer animé (une seule shared value pour synchroniser les sous-blocs).
- **Règle CRITIQUE des 3 états de chargement** :
- **premier chargement** (`isLoading && items.length === 0`) → `<SkeletonScreen>`
- **refresh** (`isLoading && items.length > 0`) → `RefreshControl` natif
- **pagination** (`isLoadingMore`) → `ListFooterComponent` (ActivityIndicator)
- **Anti-patterns** : skeleton/spinner plein écran pendant un refresh (l'utilisateur perd ses items, clignotement) ; skeleton statique sans animation (signal "ça travaille" perdu) ; skeleton avec wording "Chargement…" (double signal redondant) ; wording technique ("Liste de 0 éléments").
- **Tests env node** : `react-native-reanimated` doit être mocké (hooks no-op, `Animated.View` → string).
### Validation
- Validé le : 31-05-2026
- Contexte technique : React Native — app-alexandrie (`EmptyState.tsx`, `SkeletonScreen.tsx`, ux-cleanup-13/15)