Le modèle mental de React

C'est le module clé du guide. Si React te semble encore flou, ce n'est presque jamais un problème de syntaxe : c'est qu'il te manque le modèle mental, la bonne image dans la tête. Une fois que tu l'as, tout le reste — useState, les props, les listes, les optimisations — arrête de ressembler à de la magie et devient une suite de conséquences logiques. On va prendre le temps. Beaucoup de texte, beaucoup d'analogies, peu de code : c'est voulu. L'idée à graver est simple : un composant est une fonction qui décrit l'écran à partir de tes données, et React se charge de fabriquer cet écran à ta place.

1. Déclaratif vs impératif : la bascule mentale

Avant React, on construisait les interfaces de façon impérative. « Impératif » veut dire : tu donnes une suite d'ordres, étape par étape, en manipulant l'écran à la main. Tu trouves le bouton, tu changes sa couleur, tu trouves le compteur, tu lis l'ancien nombre, tu ajoutes un, tu réécris le texte, tu trouves le message d'erreur, tu le caches… Toi, le programmeur, tu es responsable de chaque transition entre deux états de l'écran. Tu dois te souvenir de ce qui était affiché avant pour savoir quoi modifier maintenant.

React renverse complètement cette logique : il est déclaratif. « Déclaratif » veut dire : tu ne donnes pas la suite d'étapes, tu décris le résultat voulu. Tu dis « pour ces données-là, l'écran doit ressembler à ça », et c'est React qui calcule tout seul la suite d'ordres à exécuter pour passer de l'écran actuel à l'écran décrit. Tu décris le quoi ; React s'occupe du comment. Tu ne manipules plus jamais l'écran à la main.

Cette bascule est inconfortable au début parce qu'on a l'instinct impératif : « l'utilisateur a cliqué, donc je dois aller changer ce texte ». En React, on réapprend à penser autrement : « l'utilisateur a cliqué, donc je change une donnée ; React relira ma description et mettra le texte à jour pour moi ». Tu ne touches jamais le texte. Tu touches la donnée. Toute la suite du guide repose sur ce réflexe : on agit sur les données, jamais sur l'écran.

2. UI = fonction(état) : l'équation fondatrice

On la résume souvent par une formule : UI = fonction(état). Lis-la comme une vraie équation de maths. « UI », c'est l'interface, ce que l'utilisateur voit. « état » (ou plus largement tes données), c'est l'entrée. Et la fonction, c'est ton composant. Autrement dit : l'interface est le résultat de tes données à un instant T. Donne les mêmes données, tu obtiens le même écran. Toujours. C'est déterministe, comme 2 + 2 fait toujours 4.

La conséquence est énorme et libératrice : tu n'as plus à te demander « dans quel état est l'écran en ce moment ? ». L'écran n'a pas de mémoire propre, pas de vie cachée. Il n'est que le reflet de tes données. Si tu veux savoir ce qui est affiché, tu regardes les données. Si tu veux changer ce qui est affiché, tu changes les données — et l'interface suit, automatiquement. L'écran est un miroir ; tu ne maquilles pas le reflet, tu maquilles le visage.

Voici la forme la plus simple possible d'un composant, juste pour ancrer l'équation. Repère bien l'aller-retour : des données entrent par les paramètres, une description sort par le return.

// `props` = les données qui ENTRENT dans le composant (ses réglages).
// Le composant RETOURNE une description de ce qu'on voit (du JSX).
function Greeting(props) {
  return <Text>Bonjour {props.name}</Text>;
}

// Ailleurs, on l'utilise comme une balise, en passant les données :
<Greeting name="Patrick" />   // décrit : Bonjour Patrick

Données en entrée → description en sortie. Un composant ne « fait » fondamentalement rien d'autre : il calcule à quoi l'écran doit ressembler pour les données qu'on lui donne. Ce n'est pas un objet qui vit et se modifie ; c'est une fonction qu'on rappelle.

3. Un composant = une fonction qui retourne du JSX

Maintenant qu'on a l'équation, regardons un vrai composant de Halterofit. C'est le composant Text, celui que toute l'app utilise pour afficher du texte stylé. Ne te laisse pas intimider par les types ou les détails : on cherche uniquement à reconnaître le squelette « fonction qui reçoit des données et retourne une description ».

function Text({
  className,            // ┐ on "déballe" les props directement
  asChild = false,     // │ dans les paramètres (= destructuration).
  variant = 'default', // ┘ `= 'default'` est la valeur par défaut.
  ...props             // le reste des props, regroupé d'un coup
}) {
  // ... un peu de logique interne (on la verra dans
  //     le module « useState & useEffect ») ...

  // RETOURNE le JSX : un composant texte, avec des classes de
  // style calculées et toutes les autres props transmises.
  return (
    <Component
      className={cn(textVariants({ variant }), textClass, className)}
      {...props}
    />
  );
}

Exactement le même squelette que Greeting : des données en paramètres, du JSX en retour. La syntaxe { className, variant = 'default' } est juste une façon compacte de dire « extrais-moi ces props nommées, avec ces valeurs par défaut si elles manquent ». Tout le reste n'est que décoration autour de ce squelette.

4. Le JSX, vraiment : du sucre pour des appels de fonction

Le JSX ressemble à du HTML, mais ce n'est pas du HTML, et ce n'est même pas vraiment de l'écran. C'est du sucre syntaxique : une écriture plus jolie pour quelque chose de plus brut en dessous. Sous le capot, chaque balise JSX est transformée par l'outillage (le compilateur, voir le module sur l'outillage) en un simple appel de fonction. Conceptuellement, <Text>Bonjour</Text> devient un appel du genre React.createElement(Text, null, 'Bonjour').

// Ce que TU écris (agréable à lire) :
<Text variant="h1">Halterofit</Text>

// Ce que ça DEVIENT, conceptuellement (un appel de fonction) :
React.createElement(Text, { variant: 'h1' }, 'Halterofit')

Le JSX n'est qu'une écriture confortable. En dessous, ce sont des appels de fonction qui produisent des objets JavaScript ordinaires.

Cette transformation a une conséquence capitale qu'il faut bien intégrer : le résultat du JSX n'est pas l'écran, c'est un objet en mémoire. React.createElement ne dessine rien. Il renvoie un petit objet JavaScript qui décrit un élément : « un Text, avec la prop variant: 'h1', contenant le texte "Halterofit" ». Cet objet n'a aucune existence à l'écran. C'est une fiche descriptive, une note de service.

Et comme les composants s'imbriquent les uns dans les autres — un écran contient une vue, qui contient des textes et des boutons, qui contiennent eux-mêmes des choses — le JSX d'un composant décrit en réalité tout un arbre d'éléments. Pas l'écran réel : un arbre d'objets en mémoire qui dit à quoi l'écran devrait ressembler. C'est ce point qui débloque tout le reste du module : quand ton composant « retourne du JSX », il retourne une description sous forme d'arbre, pas des pixels.

5. Les deux phases : render puis commit

Quand quelque chose change, React travaille en deux temps bien distincts. Comprendre cette séparation dissout une grande partie du flou autour de React.

Phase 1 — le « render ». React appelle tes fonctions-composants. Chacune retourne son JSX, c'est-à-dire son arbre d'éléments décrivant l'écran voulu. React assemble tous ces petits arbres en un grand arbre complet : la photo de « voilà à quoi l'écran devrait ressembler maintenant ». Cette phase se passe entièrement en mémoire. Rien n'apparaît encore à l'écran. C'est du calcul pur : React fait tourner tes fonctions et obtient une description. On appelle souvent cet arbre en mémoire le Virtual DOM (« DOM virtuel ») — une maquette légère de l'interface, dans la mémoire, qu'on peut produire et comparer très vite parce que ce ne sont que des objets JavaScript.

Phase 2 — le « commit ». React a maintenant deux descriptions : l'ancienne (ce qui est déjà affiché) et la nouvelle (ce qui vient d'être calculé). Il les compare pour repérer précisément ce qui a changé — cette comparaison s'appelle le diff (« réconciliation » dans le vocabulaire React). Puis il applique uniquement les différences à l'écran réel. Si seul un nombre est passé de 9 à 10, React ne touche qu'à ce nombre. Le reste de l'écran ne bouge pas d'un pixel.

Cette séparation render / commit éclaire beaucoup de comportements de React. Par exemple, ta fonction de rendu peut être appelée plusieurs fois « pour rien » (juste pour calculer un arbre), tant que le commit, lui, n'applique que le strict nécessaire. C'est aussi pourquoi on insiste, dans le module « useState & useEffect », pour que ton rendu reste pur : pendant la phase de render, tu te contentes de décrire ; tu ne déclenches pas d'effets de bord (pas d'appel réseau, pas de modification directe de l'écran). Décrire d'abord, agir ensuite.

6. Le flux de données unidirectionnel

React impose une règle de circulation très stricte, et c'est une bénédiction : les données circulent dans un seul sens. On parle de flux unidirectionnel. Concrètement :

• Les données descendent : un composant parent passe des données à ses enfants via les props. Comme l'eau d'une cascade, ça coule du haut (le parent) vers le bas (les enfants), jamais l'inverse.
• Les événements remontent : quand un enfant veut signaler quelque chose (« on m'a cliqué », « le texte a changé »), il ne modifie pas le parent de force. Il appelle une fonction que le parent lui a passée en prop — un callback. C'est le parent qui décide quoi faire de l'information, et qui éventuellement met à jour ses données… ce qui relance une descente de props.

Pourquoi cette contrainte rend React prévisible ? Parce que pour chaque donnée affichée, il existe un seul endroit qui en est responsable, un seul propriétaire. Quand quelque chose s'affiche mal, tu n'as pas dix suspects : tu remontes le flux jusqu'au propriétaire de la donnée et tu regardes pourquoi elle a cette valeur. Compare avec un système où n'importe quel bout de code peut modifier n'importe quel élément de n'importe où : là, un bug devient une enquête sans fin. Le flux à sens unique échange un peu de liberté contre énormément de prévisibilité — un excellent marché.

// Le PARENT possède la donnée et la fait DESCENDRE en prop,
// et passe aussi un callback pour que l'enfant fasse REMONTER l'événement.
<SetRow
  reps={12}                          // donnée qui descend (prop)
  onComplete={() => marquerFait()}   // événement qui remonte (callback)
/>

reps descend du parent vers SetRow. Quand l'utilisateur agit, SetRow appelle onComplete : l'événement remonte, et c'est le parent qui décide quoi en faire. Sens unique, toujours.

7. Les props en profondeur : en lecture seule, et composables

Les props (raccourci de « properties », propriétés) sont les données qu'un composant reçoit de son parent. C'est son entrée, ses réglages. Et il y a une règle d'or, non négociable, qui découle directement du flux unidirectionnel : vu de l'enfant, les props sont en lecture seule. Un composant peut lire ses props autant qu'il veut, mais il ne doit jamais les modifier. Elles ne lui appartiennent pas ; elles appartiennent au parent qui les lui a prêtées.

Pense à une prop comme à un document qu'on te confie en lecture. Tu peux le consulter, t'en servir pour décider quoi afficher, mais tu n'as pas le droit de raturer dessus. Si tu griffonnes sur le document du parent, plus personne ne sait quelle est la « vraie » valeur — et tu casses la belle prévisibilité qu'on vient de gagner. Si un composant a besoin de faire évoluer une donnée dans le temps, ce n'est pas une prop qu'il lui faut, c'est un état à lui (le useState du module « useState & useEffect »).

Les enfants : la prop children

Il existe une prop spéciale, children (« enfants »), qui contient tout ce que tu places entre les balises ouvrante et fermante d'un composant. C'est ce qui permet d'écrire des composants « contenants », comme une carte ou un bouton, dans lesquels on glisse n'importe quoi.

// Un composant "Carte" qui ne sait pas ce qu'il contient :
function Card({ children }) {
  return <View className="rounded-xl bg-card p-4">{children}</View>;
}

// On l'utilise en glissant du contenu À L'INTÉRIEUR des balises :
<Card>
  <Text variant="h2">Mon entraînement</Text>
  <Text>3 séries de 12</Text>
</Card>

Tout ce qui est entre <Card> et </Card> arrive dans la prop children. La carte décide juste de l'emballage (le cadre, les marges, le fond) sans rien savoir de son contenu.

Composer des composants

C'est ça, la composition : assembler des petits composants pour en former de plus grands, exactement comme on emboîte des briques Lego. Un écran d'entraînement n'est pas un bloc monolithique : c'est une Card qui contient des Text et des SetRow, chacun étant lui-même un petit composant. Cette philosophie « petites briques réutilisables qu'on emboîte » est le cœur de l'architecture de Halterofit, et on l'explore en détail dans le module sur les composants. Pour l'instant, retiens l'idée : grâce à children et aux props, tu fabriques des composants génériques (une carte, un bouton, un champ) que tu réutilises partout en changeant juste ce qu'il y a dedans.

8. Le re-render : ce que ça veut dire, et ce que ça ne veut pas dire

« Re-render » veut simplement dire : React rappelle ta fonction-composant pour obtenir une description à jour de l'écran. Souviens-toi de l'équation UI = fonction(état) : si une entrée change, il faut recalculer la sortie. Re-render, c'est exactement ce recalcul. Ça se produit dans exactement trois cas :

1. Ses props changent — le parent lui passe de nouvelles données qui descendent.
2. Son état interne change — via useState (module « useState & useEffect »).
3. Son parent re-render — par défaut, quand un parent est rappelé, ses enfants le sont aussi.

9. Un mot sur les listes : pourquoi React réclame des key

Tu vas très vite afficher des listes : la liste des exercices, des séries, des entraînements. En React, on transforme un tableau de données en un tableau d'éléments JSX. Et là, React demande une chose qui surprend au début : chaque élément de la liste doit porter une prop spéciale, key, avec une valeur unique et stable (souvent l'identifiant de la donnée).

// Chaque ligne reçoit une `key` unique et stable (ici l'id de la série).
{series.map((s) => (
  <SetRow key={s.id} reps={s.reps} />
))}

La key n'est pas pour toi ni pour l'affichage : c'est un repère que React utilise en interne pour suivre chaque élément.

Pourquoi cette exigence ? Reviens au diff. Quand la liste change — une série ajoutée, supprimée, réordonnée — React compare l'ancienne liste et la nouvelle. Sans repère, il ne peut pas savoir si la 3ᵉ ligne est « la même qu'avant qui a un peu changé » ou « une ligne complètement nouvelle ». La key est l'étiquette qui dit à React « cet élément-ci est le même qu'avant, suis-le ». Avec de bonnes keys, React déplace et conserve les éléments existants au lieu de tout détruire et reconstruire — c'est plus rapide, et ça évite des bugs subtils (un texte saisi qui saute d'une ligne à l'autre, par exemple). On creusera ça dans le module sur les composants ; pour l'instant, retiens juste : les key aident React à suivre l'identité des éléments d'une liste dans le temps.

10. Récapitulons le voyage d'un clic

Mettons toutes les pièces ensemble avec un exemple concret. L'utilisateur appuie sur « série terminée » dans Halterofit. Voici, dans l'ordre, le voyage complet à travers le modèle mental :

1. L'événement remonte : le bouton enfant appelle le callback que le parent lui avait passé en prop (flux à sens unique, événements vers le haut).
2. Le parent met à jour une donnée (son état) — il ne touche jamais l'écran à la main (pensée déclarative).
3. Cette donnée qui change déclenche un re-render : React rappelle les fonctions concernées.
4. Phase render : tes composants retournent un nouveau JSX, React calcule le nouvel arbre en mémoire (le Virtual DOM).
5. React fait le diff entre l'ancien arbre et le nouveau.
6. Phase commit : React applique uniquement les différences à l'écran réel. La série passe à « terminée ».

Remarque ce que tu n'as pas eu à faire : trouver le bouton, changer sa couleur, recompter, réécrire un texte, cacher un message. Tu as juste changé une donnée et décrit l'écran voulu. React a fait tout le sale boulot impératif à ta place. C'est ça, vivre dans le monde déclaratif.

{error !== '' && <Text className="text-destructive">{error}</Text>}