_Assistant_Lead_Tech/knowledge/frontend/patterns/general.md

Frontend — Patterns : Général

Extrait de la base de connaissance Lead_tech. Voir knowledge/frontend/patterns/README.md pour l'index complet.

---

Pattern : Focus visible interne pour champs sous overflow clip

Synthèse

• Objectif : préserver le focus visible des champs <input> / <select> quand l'app applique overflow-x: clip sur ses conteneurs (PageShell, panel, layout) — le focus outline natif est dessiné hors de la box du champ et se fait clipper.
• Contexte : app mobile-first où overflow-x: clip (ou hidden) est fréquent sur les conteneurs pour empêcher le débordement horizontal.
• Quand l'utiliser : tout projet avec une chaîne de parents en overflow: hidden|clip autour des champs de saisie.
• Quand l'éviter : si la chaîne de parents n'a pas d'overflow: hidden|clip — l'outline natif suffit.

Analyse

• Avantages :
  • aucun pixel ne sort de la box, donc aucun clip possible
  • box-shadow: inset + border-color est portable Chrome/Firefox/Safari
• Limites / vigilance :
  • outline-offset: -2px marche sur Chrome mais le rendu varie : Firefox/Safari peuvent ignorer selon la combinaison outline-style

Validation

• Validé le : 27-04-2026
• Contexte technique : CSS / mobile-first — RL799_V2

Pattern correctif (par composant)

.my-input:focus-visible,
.my-select:focus-visible {
  outline: none;
  border-color: var(--color-accent);
  box-shadow: inset 0 0 0 1px var(--color-accent);
}

Application globale au thème (recommandée pour mobile-first)

Plutôt que de répéter le pattern dans chaque composant, le pousser dans le fichier de thème global. Tous les inputs/selects/textareas en bénéficient automatiquement.

/* Dans theme/<theme>.css ou globals.css, hors :root */
input[type='text']:focus-visible,
input[type='search']:focus-visible,
input[type='email']:focus-visible,
input[type='tel']:focus-visible,
input[type='url']:focus-visible,
input[type='number']:focus-visible,
input[type='password']:focus-visible,
input[type='date']:focus-visible,
input[type='datetime-local']:focus-visible,
input[type='time']:focus-visible,
input[type='month']:focus-visible,
input[type='week']:focus-visible,
select:focus-visible,
textarea:focus-visible {
  outline: none;
  border-color: var(--color-accent);
  box-shadow: inset 0 0 0 1px var(--color-accent);
}

Pourquoi sélecteurs d'attribut explicites et pas input:focus-visible

input couvre aussi type='checkbox', type='radio', type='file', type='range', type='color' qui ont leur propre design natif. La règle pourrait casser leur rendu (carrés or autour des cases à cocher, etc.). On liste explicitement les types texte/saisie.

Conflits avec composants ayant leur propre :focus

Un composant qui a déjà .my-input:focus { ... } (sans -visible) gardera la priorité par spécificité (classe > tag). La règle globale ne joue que pour les composants qui n'ont rien défini → sûr à introduire en mid-projet.

---

Pattern : Restyle global de <input type="date"> sans wrapper JS

Synthèse

• Objectif : aligner les inputs date HTML5 sur l'identité visuelle du thème via une règle CSS globale, sans wrapper JS custom.
• Contexte : projet avec un thème dark/light custom où les inputs date natifs (icône calendrier blanche, placeholder gris OS, popover light par défaut) cassent le design.
• Quand l'utiliser : 80 % des cas (audit log, formulaires admin, profils) où la datepicker custom serait du sur-engineering.
• Quand l'éviter :
  • validation custom synchrone (range, dates blackout, format spécifique)
  • format d'affichage différent (DD/MM vs MM/DD vs ISO)
  • intégration profonde dans un design system

Analyse

• Avantages :
  • color-scheme + accent-color donnent un popover natif cohérent gratuitement
  • filtre SVG pour teinter l'icône calendrier
  • zéro JavaScript, zéro bundle additionnel
• Limites / vigilance :
  • Firefox : accent-color respecté, mais pas de pseudo-element pour customiser le placeholder
  • Safari iOS : popover sheet OS, peu personnalisable. Acceptable car cohérent avec le reste des UI iOS natives
  • filtre filter() à calibrer pour matcher la couleur du thème — chaque thème nécessite son tuning

Validation

• Validé le : 27-04-2026
• Contexte technique : CSS / inputs date HTML5 — RL799_V2

Pattern minimal

/* Toutes les variantes de pickers HTML5 */
input[type='date'],
input[type='datetime-local'],
input[type='time'],
input[type='month'],
input[type='week'] {
  color-scheme: dark; /* ou 'light' selon le thème de l'app */
  accent-color: var(--color-accent);
}

/* Place-holder OS (jj/mm/aaaa) — couleur soft */
input[type='date']::-webkit-datetime-edit-fields-wrapper,
input[type='datetime-local']::-webkit-datetime-edit-fields-wrapper {
  color: var(--color-text-soft);
}

/* Une fois saisie, couleur normale */
input[type='date']:not(:placeholder-shown)::-webkit-datetime-edit-fields-wrapper {
  color: var(--color-text-primary);
}

/* Icône calendrier teintée (filtre SVG noir → couleur d'accent soft) */
input[type='date']::-webkit-calendar-picker-indicator,
input[type='datetime-local']::-webkit-calendar-picker-indicator,
input[type='time']::-webkit-calendar-picker-indicator,
input[type='month']::-webkit-calendar-picker-indicator,
input[type='week']::-webkit-calendar-picker-indicator {
  /* Calibrer pour matcher la couleur du thème */
  filter: invert(70%) sepia(40%) saturate(450%) hue-rotate(5deg) brightness(95%);
  cursor: pointer;
  opacity: 0.85;
  transition: opacity 0.15s ease;
}

Anti-patterns

• Construire un mini calendrier JS custom pour gagner 5 % d'esthétique → effort énorme (a11y clavier, focus management, mobile, edge cases), bénéfice marginal
• Hardcoder les couleurs filter() au lieu d'utiliser des tokens du thème
• Restyler sans color-scheme: dark/light → le popover natif reste en mode clair sur thème sombre

---

Pattern : UI pour journaux / audit logs / timelines

Synthèse

• Objectif : passer d'un rendu naïf en cards uniformes "acteur · code · cible (uuid) · metadata" à une lecture rapide pour l'admin en surveillance, sans toucher au backend.
• Contexte : tout projet finit par afficher un journal d'événements (audit, activité, historique, timeline) avec metadata variable.
• Quand l'utiliser : journal avec ≥ 10 types d'actions et besoin de scanner rapidement.
• Quand l'éviter : log technique brut destiné aux devs (un <pre> peut suffire).

Analyse

• Avantages :
  • 5 patterns combinables qui améliorent radicalement la scanabilité
  • aucun changement backend (le DTO reste plat)
• Limites / vigilance :
  • reset de l'état d'expansion à chaque rechargement (l'expansion est éphémère, pas une préférence durable)

Validation

• Validé le : 27-04-2026
• Contexte technique : Vue 3 / CSS — RL799_V2 (Journal d'audit admin, 45+ types d'actions)

1. <optgroup> dérivé du préfixe label

Quand l'API retourne un catalogue d'actions avec convention Catégorie — Libellé (ex : Soirée — annulation, Tenue — création), dériver les groupes côté front au lieu de modifier le DTO.

const groupsFromLabels = computed(() => {
  const groups = new Map<string, Entry[]>();
  for (const opt of catalog.value) {
    const sep = opt.label.indexOf(' — ');
    const category = sep > 0 ? opt.label.slice(0, sep) : 'Divers';
    groups.set(category, [...(groups.get(category) ?? []), opt]);
  }
  return Array.from(groups.entries())
    .sort(([a], [b]) => a.localeCompare(b, 'fr', { sensitivity: 'base' }));
});

<select>
  <option value="">Toutes les actions</option>
  <optgroup v-for="[cat, opts] in groupsFromLabels" :label="cat" :key="cat">
    <option v-for="o in opts" :value="o.value" :key="o.value">{{ o.label }}</option>
  </optgroup>
</select>

Bénéfice : 1 seul clic pour filtrer (vs cascade 2 selects), accessible natif, zéro modif backend.

2. Code couleur sémantique par catégorie

Barre de couleur de 3 px à gauche de chaque card de la liste, mappée sur la catégorie de l'événement. Transforme un mur de cards uniformes en lecture instantanée.

.log-item {
  border-left: 3px solid var(--log-cat-color, var(--color-border));
}
.log-item--cat-soiree { --log-cat-color: var(--color-accent-primary); }
.log-item--cat-rgpd   { --log-cat-color: var(--color-accent-danger); }

Pourquoi pas le fond complet : trop bruyant, perd la sobriété d'un journal admin. La barre latérale signale sans crier.

3. UUIDs rétrogradés en monospace soft

Les UUIDs / IDs techniques affichés en plein texte cassent la lecture humaine. Les détecter via regex et les rendre en font monospace + couleur soft + taille réduite, sans les masquer (utiles pour forensics).

const UUID_RE = /[0-9a-f]{8}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{12}/gi;

.uuid {
  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
  font-size: 0.78em;
  color: var(--color-text-soft);
  word-break: break-all;
}

4. Date relative + absolue en tooltip

Pour la lecture humaine, "il y a 5 min" / "hier" / "il y a 3 j" bat toujours "27 avril 2026 à 08:37". La date absolue reste accessible en title du <time> pour les forensics.

const formatRelative = (iso: string) => {
  const diff = (Date.now() - new Date(iso).getTime()) / 1000;
  if (diff < 60) return 'à l\'instant';
  if (diff < 3600) return `il y a ${Math.round(diff / 60)} min`;
  if (diff < 86400) return `il y a ${Math.round(diff / 3600)} h`;
  if (diff < 172800) return 'hier';
  if (diff < 604800) return `il y a ${Math.round(diff / 86400)} j`;
  return new Date(iso).toLocaleDateString('fr-FR', {
    day: 'numeric', month: 'short', year: 'numeric',
  });
};

5. Détails techniques repliables

La metadata détaillée (clés/valeurs verboses, IDs internes, raisons null) sert à l'investigation, pas à la lecture courante. La masquer derrière un Voir les détails / Masquer les détails, et reset l'état d'expansion à chaque rechargement.

const expanded = ref<Set<string>>(new Set());
const toggle = (id: string) => {
  const next = new Set(expanded.value);
  next.has(id) ? next.delete(id) : next.add(id);
  expanded.value = next;
};
// Reset après chaque load
const loadList = async () => {
  /* … */
  expanded.value = new Set();
};

Le bouton "voir détails" n'apparaît que si la card a effectivement de la metadata. Un toggle vide pollue la grille visuelle.

Anti-patterns à éviter

• Cards uniformes en couleur/border quel que soit le type d'événement → tue la scanabilité
• Date absolue toujours visible (27 avril 2026 à 08:37) sur des cards serrées → bruit cognitif inutile
• UUIDs en plein texte sans rétrogradation visuelle
• Cascade 2 selects quand un <optgroup> natif suffit
• Bouton "voir détails" affiché même sans détails à voir
• Persister l'expansion entre navigations / paginations → état orphelin

---

Pattern : Structuration de pages admin (eyebrows + grille filtres + variante danger)

Synthèse

• Objectif : poser une grammaire visuelle commune sur les écrans admin (filtres + liste/form + sections multiples) sans framework lourd.
• Contexte : module Admin avec plusieurs panels (Audit, Utilisateurs, Corbeille, etc.) qui partagent la même structure.
• Quand l'utiliser : ≥ 3 panels admin avec structure similaire.
• Quand l'éviter : page admin unique sans cohérence inter-panels à maintenir.

Validation

• Validé le : 27-04-2026
• Contexte technique : Vue 3 / CSS — RL799_V2 (5 panels admin)

1. Eyebrows de section

Au lieu de titres H2/H3 trop forts, utiliser des "eyebrows" : mini-labels uppercase, letter-spacing élargi, taille caption, couleur d'accent.

.eyebrow {
  text-transform: uppercase;
  letter-spacing: 0.2em;
  font-size: var(--font-size-caption);
  color: var(--color-accent);
  margin: 0;
}

<p class="eyebrow">Filtres</p>
<div class="my-filters"><!-- … --></div>

<p class="eyebrow">Résultats <span class="eyebrow-count">· {{ total }} entrées</span></p>
<div class="my-list"><!-- … --></div>

Le compteur (· N entrées) est en font-weight: normal, sans uppercase, en color-text-secondary — typographie en cascade.

Bénéfice : structure visuelle sans concurrencer un éventuel titre de page. Cohérence inter-écrans dans tout un module si l'eyebrow est utilisé partout.

Quand ne pas afficher l'eyebrow Résultats : sur loading / error / empty state. Le StateBlock (ou équivalent) prend le relais.

2. Grille de filtres hiérarchique

Quand 3+ filtres dont l'un est dominant (typiquement une recherche), au lieu d'un flex-wrap chaotique, utiliser une grille avec le filtre primaire en pleine largeur :

<div class="filters">
  <label class="filters__label filters__label--full">Recherche
    <input type="search">
  </label>
  <label class="filters__label">Statut <select><!-- … --></select></label>
  <label class="filters__label">Rôle <select><!-- … --></select></label>
</div>

.filters {
  display: grid;
  grid-template-columns: 1fr 1fr;
  align-items: end;
  gap: var(--space-2);
}
.filters__label--full {
  grid-column: 1 / -1;
}

3. Variante danger pour actions destructives

Sur un écran qui mélange actions constructives et destructives (ex : saisie initiale + bypass admin) :

.btn--danger {
  border-color: color-mix(in srgb, var(--color-danger) 48%, transparent);
  background: color-mix(in srgb, var(--color-danger) 12%, transparent);
  color: var(--color-danger);
}

.card--danger {
  border-left: 3px solid var(--color-danger);
}

color-mix produit un rouge soft (12-20 % saturation), pas un flash rouge violent.

Anti-pattern : background: red / color: red directs ou hex hardcodés (#ef4444). Toujours via tokens du thème.

Anti-patterns à éviter

• Filtres en flex-wrap qui produisent 3 lignes asymétriques selon le viewport
• 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

---

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

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');
};

---

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)

---

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

switch (model.action) {
  case 'paywall':
    if (__DEV__) throw new Error('[story-X] CTA paywall atteint — invariant cassé ?');
    return; // prod : no-op safe
  // …
}

---

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

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" />

---

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

// ✅ l'icône check reste visible, hors du ternaire isLoading
<View style={containerStyle}>
  {isFollowing && <Icon name="check" />}
  {isLoading ? <Spinner /> : <Label>{label}</Label>}
</View>

---

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

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;
}

---

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)

---

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)

---

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

ctaButton: { minHeight: 44, minWidth: 44, justifyContent: 'center', alignItems: 'center' }

---

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

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'; ... }

---

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

<AvatarInitial name={"charlie" | null} size={40} />

---

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)