Merge branch '73-doc-improve-a-component' into 'master'

Resolve "doc: improve a component"

Closes #73

See merge request !46

doc/sections.md

@@ -2,7 +2,7 @@
  
 Docusaurus étant un Framework de la librairie React, on y retrouve la même logique.
 
-L'affichage d'une page web est un ensemble de composants réutilisables, que l'on peux assembler.
+L'affichage d'une page web est un ensemble de composants réutilisables, que l'on peut assembler.
 
 Nous allons nous appuyer sur l'utilisation de ces Composants pour créer nos différentes sections d'affichage, notamment pour gérer le rendu visuel de la page d'accueil du site `index.js`.
 
@@ -16,12 +16,10 @@ Pour l'exemple, nous allons expliquer comment nous avons créer la section charg
 
 Dans le dossier `src/components/`, nous avons créé un fichier React `HomepageFeatures.js`.
 
-
 Nous avons choisi de nommer notre fichier `HomepageFeatures`, en [PascalCase](https://techlib.fr/definition/pascalcase.html), car ce composent est destiné à être affiché, dans la `Homepage` (page d'Accueil) et doit afficher les `Features` (fonctionnalités) de Froggit.
 
 Ce fichier est composé de 3 parties:
 
-
 - une pour gérer les données de notre section ;
 - une pour définir les comportements que nous attendons en utilisant différentes fonctions ;
 - une pour définir l'affichage. Nous utilisons le JSX pour cette partie, voir l' [introduction au JSX](https://fr.reactjs.org/docs/introducing-jsx.html) sur la doc de React pour des explications sur cette extension syntaxique du JavaScript.
@@ -29,6 +27,7 @@ Ce fichier est composé de 3 parties:
 ### Les données de notre section
 
 Nous allons créer un tableau d'objets JavaScript pour définir les données à afficher dans notre section. Il y a 3 objets pour chaque élément du tableau :
+
 1. Un titre, de type `chaîne de charactère` (_String_), donc entouré de guillements simples `'` ou doubles `"`).
 2. Une description, que nous définissons en tant qu' `Element JSX`. Nous pouvons ainsi lui donner un _template_ de rendu comme valeur, avec les balises HTML de notre choix, juste un paragraphe dans notre cas. Pour cela, nous devons définir sa valeur entre des parenthèses et à l'intérieur d' une balise parent, pouvant être une `div`, ou  comme nous utilisons ci-dessous, avec une simple balise vide.
 3. Une image, que nous définissons en tant que `Composant React`, afin de simplifier la syntaxe de notre code dans les prochaines étapes notemment pour définir notre affichage. Comme cette image est un composant, nous la nommons `Svg` en PascalCase. 
@@ -79,6 +78,94 @@ const FeatureList = [
 
 Notre section affichera les 4 éléments, chacune avec un titre, une description et une image en Svg.
 
+### Les paramètres d'un composant
+
+On peut passer des paramètres au composant grâce :
+
+- au propriété de la balise ;
+- au texte entre les balises ouvrante et fermantes.
+
+Pour notre exemple on va créer le compostant `TextRight` avec deux paramètres :
+
+1. une image
+2. un bloc de texte
+
+On va utiliser ce composant depuis un fichier MDX.
+
+Le fichier  `TextRight.js` se trouve dans le répertoire des composants :  `src/components`. Comme on a du CSS exclusif à ce composant on crée un fichier avec la même base de nom :`TextRight.module.css`. Le `.module.css` signifie qu'il apportera des modifications uniquement au fichier `.js` pourtant le même nom, et pas les autres page du site.
+
+#### Le composant
+
+```jsx
+// src/components/TextRight.js
+import React from "react";
+import styles from "./TextRight.module.css";
+import useBaseUrl from '@docusaurus/useBaseUrl';
+
+export default function TextRight({children, img}) {
+  return (
+    <>
+      <div className="row">
+        <div className="col col--6">
+          <img src={useBaseUrl(img)} />
+        </div>
+        <div className="col col--6">
+          {children}
+        </div>
+      </div>
+    </>
+  );
+}
+```
+
+D'abord on fait ses imports : React, le module css, et un useBaseUrl.
+
+On utilise `useBaseUrl` pour obtenir l'URL de base du site et pouvoir avoir renvoyer les bonnes URL au HTML sui sera généré. Voir la doc de [Docusaurus](https://docusaurus.io/fr/docs/static-assets#in-jsx).
+
+On exporte la fonction (qui sera importée ensuite dans le fichier mdx). Cette fonction possède deux paramètres :
+
+1. `children`, reprenant les propriétés des "parents" pour les renvoyer en sortie, c'est ce qui se trouve entre les deux balises du composant React.
+2. `img` qui contient le chemin relatif de notre image depuis le répertoire` static/` et qui sera passé dans les propriété de la balise ouvrante de notre composant au moment de l'appel.
+
+La fonction génère du HTML, se qui se trouve dans `return` :
+
+- Des "blocks" (`div`) avec des `className` (ou des class en html). 
+- Pour l'image on utilise le fonction `useBaseUrl` qui renvois l'URL finale de notre `img` (en paramètre). 
+- Pour notre texte il est contenu dans le paramètre children. 
+
+Dans le dossier `static/` : mettre l'image en veillant à bien choisir son nom.
+
+#### L'appel du composant
+
+Dans le dossier `src/pages` : on à un fichier [MDX](https://docusaurus.io/fr/docs/markdown-features/react), `communaute.mdx` dans notre exemple.
+
+Dans notre fichier MDX il faut :
+
+- Importer la fonction `TextRight` depuis le chemin du composant.
+- Utiliser le composant avec la nouvelle balise créé `<TextRight>` et `</TextRight>`
+
+Comme par exemple :
+
+```markdown
+import TextRight from '@site/src/components/TextRight';
+
+<TextRight img="/img/mon_image.png">
+
+# Mon Titre
+
+Mon texte
+
+</TextRight>
+```
+
+### Attention au multiples CSS
+
+⚠️ **Remarque: veiller aux erreurs dans les fichiers `custom.css` et `.module.css`.**
+
+Nous avons constaté que si une classe reçoit des attribues dans le fichier `mon_composant.module.css` et le fichier `custom.css` alors il sera retenu en priorité ce qui se trouve dans le fichier `custom.css` qui est le fichier général de style.
+
+Nous n'avons pas de réponse à la question :
+> Est-ce que ce qui se trouve dans le fichier `mon_composant.module.css` s'ajoute à ce qui se trouve dans le fichier `custom.css` ?
 
 ### Affichage
 
@@ -118,10 +205,9 @@ Ainsi, notre composant va renvoyer notre Svg en image, le titre en `h3` et la de
 Nous devons également importer certains utilitaires, selon nos besoins (la librairie React, les modules CSS), puis exporter notre composant, pour qu'il puisse être réutilisé.
 Il est nécessaire d'utiliser le système d'import/export de [modules JavaScript](https://javascript.info/import-export).
 
+### Définition des Comportements
 
-### Définition des Comportements 
-
-Nous itérons sur chaque élément de notre tableau, en utilisant la méthode JavaScript `.map`, qui est très souvent utilisé dans les Composants React. 
+Nous itérons sur chaque élément de notre tableau, en utilisant la méthode JavaScript `.map`, qui est très souvent utilisé dans les Composants React.
 
 La méthode map() crée un nouveau tableau avec les résultats de chaque élément du tableau. [Voici un tutoriel expliquant cette méthode](https://www.freecodecamp.org/news/javascript-map-how-to-use-the-js-map-function-array-method/).
 
@@ -172,11 +258,12 @@ export default function Home() {
 }
 ```
 
-Entre nos balises `Layout`, nous retrouvons 3 composants enfants, d'abord l'entête (_header_) nommé <HomepageHeader /> qui a été créé à l'intérieur même de ce composant.
+Entre nos balises `Layout`, nous retrouvons 3 composants enfants, d'abord l'entête (_header_) nommé `<HomepageHeader />` qui a été créé à l'intérieur même de ce composant.
+
+Puis nous retrouvons 2 Composants, qui ont été importé depuis le dossier `src/components/`:
 
-Puis nous retrouvons 2 Composants, qui ont été importé depuis le dossier `src/components/`: 
-1. <HomepagePromises />, pour la section des promesses 
-2. <HomepageFeatures />, pour la section des fonctionnalités
+1. `<HomepagePromises />` pour la section des promesses
+2. `<HomepageFeatures />` pour la section des fonctionnalités
 
 ## Feuille de style CSS
 

doc/theme.md

@@ -13,3 +13,35 @@ html[data-theme='dark'] .menu__link {
 ```
 
 Pour les couleurs, **Infima** utilise un nuancier sur [Colorbox](https://colorbox.io/).
+
+## Le Swizzling
+
+Docusaurus propose une méthode pour personnaliser le thème : c'est le [Swizzling](https://docusaurus.io/fr/docs/swizzling).
+
+On échange un composant de thème généré par Docusaurus, par le notre.
+Il en existe deux types :
+
+1. **Éjection** : créer une copie du composant de thème à personnaliser.
+2. **Enveloppement** : on améliorer le composant de thème existant.
+
+### Éjection
+
+**Pour procéder à l'éjection, on lance dans son terminal la commande suivante :**
+
+```sh
+npm run swizzle [nom du thème] [nom du composant] -- --eject
+```
+
+### Enveloppement
+
+**Pour l'enveloppement, procéder comme suit :**
+
+```sh
+npm run swizzle [theme name] [component name] -- --wrap
+```
+
+En exemple, de notre Footer :
+En lançant la commande de l'enveloppement, il nous crée le répertoire `theme/Footer`.
+Le fichier `index.js` s'y trouvant est notre nouveau Footer.
+
+Nous avons enveloppé notre Footer avec de nouveaux éléments.