Aller au contenu principal

Quel est le mode de fonctionnement d'écriture des composants présentationels ?

Le but de cette documentation est de décrire le workflow ainsi que la réflexion à avoir lorsque l'on construit des composants présentationels.

Les différents types de composants​

Avant d'expliquer les différentes étapes de création des composants, il est important de comprendre les deux types principaux de composants dans l'application.

Les composants atomiques​

Ces composants sont les éléments de base de l'application. Ils servent de blocs de construction aux éléments de l'application. Un bouton ou un input sont des exemples classiques de composants atomiques.

Les composants "métiers"​

Ce sont les composants qui sont directement liés au métier de l'application. Par exemple, un composant permettant d'afficher une carte de publication dans un réseau social.

La plupart du temps, ces composants prendront des props qui seront un ou plusieurs types définis dans le dossier types. Ce composant affichera ensuite les informations de l'élément en utilisant principalement des composants atomiques.

Les éléments importants à prendre en compte pour ce type de composants​

Liens vers d'autres pages​

Les liens vers d'autres pages devront être dans des NextLink (détail de la publication dans notre exemple).

Interactions avec l'utilisateur​

Les interactions avec l'utilisateur (appui sur le bouton "like" par exemple) devront être gérées par des fonctions passées en props (onLike dans notre exemple). Il faudra également penser à gérer les états de chargement (like en cours).

Première étape : écriture des types Typescript​

Afin de s'assurer que le mode de fonctionnement des composants correspond bien au métier, il faudra que les types Typescript soient créés avant le début du développement ou de la création des composants.

Pour savoir où créer ces types, il faudra se référer à la documentation sur la création des types Typescript.

Deuxième étape : inventaire des composants à créer​

Une fois les types créés et clairs pour la partie intégration, il faudra lister les composants à créer.

Si une maquette Figma a été faite, il pourra être intéressant de se baser en partie sur les différents composants présents dans la maquette.

Le but sera de pouvoir décrire sur les différentes pages, les composants qui seront utilisés. Excalidraw sera un outil intéressant dans ce cadre, pensez à utiliser le compte ITN (excalidraw@itnetwork.fr) afin de faire le schéma dans la collection du projet.

Voici un exemple de hiérarchie de composants pour une page: https://link.excalidraw.com/l/2hU5yX8q4j/10Ubaa55LVy

Les composants seront à créer dans le dossier front/components/presentational.

Une issue sera à créer contenant la liste des composants à créer.

Un exemple est disponible ici

Troisième étape : création du thème​

Elements de base du théme chakra

Lors de la création du théme, il est important de définir tous les éléments de base de l'application

Breakpoints​

info

Les composants chakra utilisant des breakpoint devront obligatoirement référencer le token sématique du break point (md par exemple) et non pas une valeur arbitraire en rem, px, ...

Typographie​

info

Les composants chakra utilisant des breakpoint (quel que soit la syntaxe utilisée) devront obligatoirement référencer le token sémantique du break point (md par exemple) et non pas une valeur arbitraire en rem, px,… Si cette règle n'est pas respectée, un commentaire devra en indiquer la raison.

Espacements​

info

Afin de garder une cohérence sur les espacements dans l'application, tous les espacements (margin, padding, )

Couleurs​

info

Il est recommandé de définir les couleurs sous forme de "shade" afin de pouvoir utiliser le principe dans les colorScheme de composants. Il est recommandé d'utiliser la notation HSL afin de pouvoir plus facilement voir la différence de luminosité entre les différentes couleurs.

Quatrième étape : création des stories et des composants​

Création des stories de pages​

Le but est de créer les pages (organisms) une à une dans le storybook en tant que story indépendante. Ces pages nécessiteront la création de composants (atoms ou molecules) métiers au fur et à mesure de leur construction.

Création des composants métiers​

La création des pages va amener à la création des composants métiers, qui eux même vont conduire à la création des composants atomiques.

Chaque composant métier devra avoir sa propre story dans le storybook.

Création des composants atomiques​

Pour les composants atomiques, le choix sera laissé à l'intégrateur sur la création d'une story (il peut être pertinent de faire une story pour les boutons afin de montrer les différents variant, tailles et colorScheme, mais pas forcément pour tous)

Composants Chakra​

// front/components/presentational/Button.tsx
import { defineStyle, defineStyleConfig } from "@chakra-ui/react";

const baseStyle = defineStyle({
  textTransform: "uppercase",
  fontWeight: 800,
  letterSpacing: 1,
  paddingTop: 0.5,
  paddingRight: 4,
  paddingBottom: 0.5,
  paddingLeft: 4,
  borderRadius: 5,
  transition: "all .2s ease-in-out",
});


const customVariant = defineStyle((props) => {
  const { colorScheme: c } = props

  return {
    bg: `${c}.500`
  };
});

export const buttonTheme = defineStyleConfig({
  baseStyle,
  variants: {
    customVariant
  },
  defaultProps: {
    size: "sm",
    colorScheme: "brand",
  },
});

attention

Dans le cadre du bouton il ne faut pas confondre la notion de variant (ghost, outline,…) et la notion de couleur (blue, cyan,…) Pensez à observer le fonctionnement du thème de base des éléments que vous souhaitez modifier. Exemple pour le bouton Le lien se trouve systématiquement dans la documentation du composant sur le site de chakra img.png

attention

Les boutons et les champs de formulaires doivent pouvoir cohabiter harmonieusement.

En d'autres termes, un champ de formulaire (<input type='text'>, <select>, …) et un button doivent pouvoir être accollés de telle sorte que cela ne soit pas choquant.

Par conséquent, il faut qu'ils aient la même hauteur, la même font-size, les mêmes padding verticaux, line-height, que leurs libellés/placeholder soient alignés verticalement, etc…

Cela implique que les props, (notamment size : xs, sm, md, lg ou xl) soient cohérentes pour chacun d'entre eux.

Composants custom​

Lorsque c'est possible, il faut privilégier l'utilisation de la création de composants chakra afin de garder la possibilité de modifier le fonctionnement du composant sans ajouter de props spécifiques.

info

Si un composant atomique existe déjà dans Chakra, il faut l'utiliser (Button par exemple). Si un choix est fait de ne pas utiliser un composant Chakra, il faudra justifier ce choix dans l'issue d'inventaire des composants.

info

Il peut arriver dans certains cas que des composants n'aient pas vocation à être utilisés dans le projet mais seulement dans le storybook.

Par exemple un composant permettant d'afficher une liste de données de manière spécifique. Ces composants seront à créer dans le dossier front/stories/components.

Ces composants ne devront pas être utilisés dans l'application.

TODO​

  • Storybook action ou interaction ?
  • Chakra et typescript ?

Ressources intéressantes​