Cours Vibe coding avec Claude Code · Module 14: Clone de Pinterest

Carte au trésor en colonnes : une grille masonry à partir d'un croquis

12 min de lecture
Dans cette leçon12

Ohé ! Dans cette location, tu construis Treasure Map, un clone de Pinterest, c'est-à-dire d'un service où les gens épinglent des images inspirantes sur des tableaux. Une image avec un titre et un auteur s'appelle un pin. Le souci commence sur la page d'accueil : les photos n'ont pas la même hauteur, et une grille ordinaire les range en rangées aussi hautes que la photo la plus haute, ce qui laisse des trous sous les plus basses. La disposition masonry (un mur de briques) a des colonnes, et chaque nouveau pin va dans celle qui est la plus basse à cet instant. Comme le quartier-maître qui pose sa nouvelle caisse sur la pile la plus basse.

Ce que tu vas apprendre

  • donner un croquis de la disposition à Claude et vérifier qu'il l'a lu comme toi ;
  • lire l'algorithme de la colonne la plus basse et reconnaître un état modifié pendant le rendu ;
  • choisir le nombre de colonnes selon la largeur de la fenêtre sans erreur d'hydratation ;
  • réserver la place d'une image avant son chargement et soigner le focus au clavier ;
  • commander un défilement infini avec une sentinelle, sans requêtes en double.

Nouveau port : le projet treasure-map

Le clone est une application à part : tu la crées donc avec la commande de la leçon 1_2, en changeant seulement le nom :

npx create-next-app@latest treasure-map --ts --eslint --tailwind --app --no-src-dir --no-cache-components --agents-md --no-agent-feedback --use-npm

Ensuite, la boucle habituelle : une session claude, un CLAUDE.md qui importe @AGENTS.md (leçon 1_7), Vitest avec le correctif @types/node de la leçon 4_1 et un premier commit. Dans public/pins/, dépose une quinzaine de photos larges de 600 pixels et de hauteurs différentes, à toi ou des planches colorées faites avec ffmpeg, comme dans la leçon 12_1. Les images du projet n'ont pas besoin d'une entrée remotePatterns de la leçon 3_1.

Un croquis plutôt qu'une description

Une disposition en colonnes se dessine plus facilement qu'elle ne se décrit. Dessine sur une feuille quatre colonnes de rectangles de hauteurs différentes et enregistre la photo sous croquis/masonry.png. Tu la donneras par son chemin de fichier, comme dans la leçon 3_2. Le croquis montre l'apparence, pas le comportement : le nombre de colonnes sur téléphone et la gestion de la touche Tab doivent figurer dans le texte de la demande.

Demande pour Claude Code

Le changement touche des données, une fonction, trois composants et une page : tu commences donc par un plan, comme dans la leçon 1_6 :

Demande pour Claude Code :

/plan D'abord, décris ce que tu vois sur le croquis croquis/masonry.png.
Ensuite, planifie la page d'accueil de Treasure Map : une grille masonry
de pins venus de lib/pins.ts (images de public/pins, chaque pin a width,
height et dominantColor). Chaque pin va dans la colonne la plus basse ;
calcule la répartition dans une fonction pure lib/masonry.ts, pas dans
un état. Colonnes : 2 sur téléphone, 3 dès 768 px, 4 dès 1024 px, sans
erreur d'hydratation. La place de l'image est réservée avant le
chargement, fond de la couleur dominante. Carte de pin : bouton
Enregistrer en haut à droite, titre et auteur en bas, visibles au
survol de la souris et au focus clavier. D'abord les tests de
lib/masonry.ts. Ce sera fini quand npm run test -- --run, npm run lint
et npx tsc --noEmit passent sans erreur.

Dans le plan, lis la description du croquis et vérifie que la répartition est une fonction pure et d'où Claude tirera la largeur de la fenêtre. Si le plan n'en dit rien, corrige-le avec Ctrl+G.

Ce que Claude a écrit : les données du pin

Ouvre lib/types.ts dans Cursor. Le pin n'a que les champs qu'utilise cette leçon :

// lib/types.ts
export interface Pin {
  id: string;
  title: string;
  author: string;
  src: string;
  width: number;
  height: number;
  dominantColor: string; // "#rrggbb"
  tags: string[];
}

width et height sont les dimensions du fichier en pixels, pas la taille à l'écran. dominantColor est la couleur la plus présente sur la photo, calculée une seule fois, à l'ajout du fichier. Les tags serviront dans la leçon 13_3.

Ce que Claude a écrit : la colonne la plus basse

Ouvre lib/masonry.ts. Tout l'algorithme tient dans une boucle qui prend les pins un par un et ajoute chacun à la colonne la plus basse à cet instant :

// lib/masonry.ts
export function distributePins<T extends Sized>(pins: readonly T[], columnCount: number): T[][] {
  const columns: T[][] = Array.from({ length: columnCount }, () => []);
  const heights: number[] = new Array(columnCount).fill(0);
  for (const pin of pins) {
    const shortest = heights.indexOf(Math.min(...heights));
    columns[shortest].push(pin);
    heights[shortest] += pin.height / pin.width; // hauteur pour une colonne de largeur 1
  }
  return columns;
}

Sized est un type de ce fichier : tout ce qui a width et height. Math.min(...heights) trouve la hauteur la plus basse et indexOf le numéro de sa colonne ; en cas d'égalité, la colonne de gauche gagne. Les colonnes ont la même largeur, donc la dernière ligne n'ajoute que la proportion height / width : il n'y a pas besoin de connaître les pixels à l'écran. La fonction ne modifie pas le tableau reçu, elle en construit de nouveaux.

Parmi les cinq tests, retiens celui-ci : "ajouter des pins ne déplace pas les précédents". La boucle parcourt les pins dans l'ordre, donc quand on charge les pages suivantes, rien ne saute sous les yeux du spectateur. Résultat chez nous : Tests 5 passed (5).

L'erreur typique : un état modifié pendant le rendu

La première version de l'agent, que tu trouveras dans beaucoup de tutoriels, gardait les hauteurs des colonnes dans un état :

// components/MasonryGrid.tsx (version de l'agent)
const [columnHeights, setColumnHeights] = useState<number[]>(Array(columns).fill(0));
const distributePins = () => {
  // ... la même boucle que ci-dessus
  setColumnHeights(heights);
  return columnArrays;
};
const columnArrays = distributePins();

Le rendu appelle distributePins, qui met l'état à jour avec un nouveau tableau ; React rend donc le composant une fois de plus, et celui-ci modifie de nouveau l'état. Chez nous, la page a répondu par un code 500 et la console a affiché Too many re-renders. React limits the number of renders to prevent an infinite loop. De toute façon, personne ne lisait l'état columnHeights. npm run lint a attrapé l'erreur avant le navigateur : Cannot call setState during render (règle react-hooks/set-state-in-render), alors que npx tsc --noEmit est resté muet. Le remède, c'est le linter lui-même qui le suggère : ce qui se calcule à partir des props se calcule pendant le rendu, sans état. C'est pourquoi MasonryGrid n'a qu'une seule ligne : const columns = distributePins(pins, columnCount).

Ce que Claude a écrit : le nombre de colonnes sans erreur d'hydratation

Le serveur produit le HTML avant que le navigateur ne le voie, donc il ne connaît pas la largeur de la fenêtre. L'agent aime écrire typeof window === "undefined" ? 2 : .... Chez nous, le serveur a envoyé "2", le navigateur a calculé "4" et React a signalé Hydration failed because the server rendered text didn't match the client. L'hydratation est le moment où React reprend le HTML du serveur et y branche les évènements. Ouvre lib/columns.ts :

// lib/columns.ts
export function useColumnCount(): number {
  return useSyncExternalStore(
    subscribe,
    () => columnsForWidth(window.innerWidth),
    () => 2, // le serveur ignore la largeur de la fenêtre : il rend 2 colonnes, le navigateur corrige après hydratation
  );
}

useSyncExternalStore est le hook de React pour les valeurs qui changent en dehors de React. subscribe écoute l'évènement resize de la fenêtre, la deuxième fonction transforme la largeur en 2, 3 ou 4 colonnes, et la troisième est la version pour le serveur. Selon la documentation de React, elle ne sert que sur le serveur et pendant l'hydratation : le premier rendu dans le navigateur correspond donc au HTML du serveur, puis React refait un rendu avec la vraie largeur. Le prix à payer est un bref éclair de deux colonnes sur un écran large. React compare les résultats avec Object.is, donc déplacer le bord de la fenêtre dans la même plage ne provoque pas de nouveau rendu.

Ce que Claude a écrit : la carte du pin

Ouvre components/PinCard.tsx. La photo :

// components/PinCard.tsx
<figure className="group relative overflow-hidden rounded-2xl" style={{ backgroundColor: pin.dominantColor }}>
  <Image
    src={pin.src}
    alt={pin.title}
    width={pin.width}
    height={pin.height}
    sizes="(min-width: 1024px) 25vw, (min-width: 768px) 33vw, 50vw"
    loading={eager ? "eager" : "lazy"}
    className="h-auto w-full"
  />

Selon la documentation de next/image, le navigateur calcule la proportion à partir de width et height et réserve la place avant le chargement de l'image. D'ici là, on voit un rectangle de la couleur dominante, donc la page ne saute pas. Les pins des deux premières rangées reçoivent eager. L'agent écrit souvent ici priority, que la documentation de Next.js 16 marque comme obsolète au profit de preload, et dans la plupart des cas elle conseille loading="eager" ou fetchPriority="high". preload ne convient pas non plus là où le plus grand élément peut être l'une de plusieurs images, comme dans une mosaïque. Sur la photo repose un voile :

// components/PinCard.tsx
<div className="absolute inset-0 flex flex-col justify-between bg-black/40 p-3 opacity-0 transition-opacity group-focus-within:opacity-100 group-hover:opacity-100">

Le voile est affiché par le CSS seul : group-hover au survol de la souris et group-focus-within quand le focus est sur un bouton à l'intérieur. L'ancien code faisait les deux à la fois, avec l'état isHovered et la classe group-hover ; un seul mécanisme suffit, et le CSS ne refait pas le rendu du composant à chaque mouvement de souris. Le bouton Enregistrer, en haut à droite, a un aria-label avec le titre, par exemple "Enregistrer le pin : Crique à l'aube", car trente-six "Enregistrer" identiques sonnent tous pareil dans un lecteur d'écran. Il a aussi un contour focus-visible, et le titre et l'auteur se tiennent en bas. Chaque colonne est une liste ul, donc Tab descend d'abord toute la première colonne : c'est le prix d'un masonry calculé en JavaScript.

Défilement infini : la sentinelle

La première page compte douze pins, et les suivants doivent arriver seuls quand le spectateur approche de la fin. La deuxième demande :

/plan Ajoute le défilement infini. Un Route Handler GET /api/pins?cursor=
renvoie 12 pins et nextCursor (null à la fin). Le composant PinFeed
charge la page suivante quand l'élément sentinelle sous la grille
approche de l'écran : IntersectionObserver, élément via useRef. Pas de
requêtes en double ni de valeurs périmées dans la fermeture. En fin de
liste, un message à la place de la sentinelle. À la fin : lint, tsc et
build.

La route app/api/pins/route.ts lit cursor dans l'adresse et renvoie getPinPage(cursor). Ici, le curseur est le numéro du premier pin de la page suivante. Ouvre components/PinFeed.tsx et trouve l'effet qui surveille la sentinelle et charge les pages suivantes :

// components/PinFeed.tsx
useEffect(() => {
  const sentinel = sentinelRef.current;
  if (!sentinel || cursor === null) return;
  let cancelled = false;
  const observer = new IntersectionObserver(
    (entries) => {
      if (!entries[0].isIntersecting) return;
      observer.disconnect(); // une page par entrée de la sentinelle
      fetch(`/api/pins?cursor=${cursor}`)
        .then((res) => res.json() as Promise<PinPage>)
        .then((page) => {
          if (cancelled) return;
          setPins((prev) => [...prev, ...page.pins]);
          setCursor(page.nextCursor);
        });
    },
    { rootMargin: "0px 0px 600px 0px" },
  );
  observer.observe(sentinel);
  return () => {
    cancelled = true;
    observer.disconnect();
  };
}, [cursor]);

C'est une version abrégée : le vrai fichier vérifie aussi res.ok et affiche un message d'erreur dans .catch. La sentinelle est un div vide sous la grille, et IntersectionObserver prévient quand elle entre dans le champ de vision. Selon MDN, rootMargin élargit la zone d'observation, ici de 600 pixels vers le bas : le chargement démarre donc avant la fin de la liste. cursor figure dans les dépendances de l'effet, donc chaque page reçoit un nouvel observateur avec le curseur à jour et rien ne lit une ancienne valeur. disconnect() après la première détection donne une requête par entrée de la sentinelle, et prev => ... ajoute les pins à la liste la plus récente. Quand nextCursor vaut null, il n'y a plus d'observateur, et à la place de la sentinelle s'affiche le message "Voilà tous les trésors de cette carte."

La revue du capitaine

  1. État dans le rendu. Cherche setColumn dans le projet (Cmd+Shift+F). Un état modifié dans le corps d'un composant est signalé par npm run lint ; ne désactive jamais cette règle avec un commentaire.
  2. Hydratation. Cherche typeof window, puis ouvre la page dans une fenêtre large : la console doit rester vide. Chez nous, Chrome a affiché 4 colonnes à 1280 pixels, 3 à 800 et 2 à 700, sans rechargement.
  3. Clavier. Ouvre la page et appuie sur Tab. Chez nous, le focus est arrivé sur "Enregistrer le pin : Crique à l'aube", le voile est apparu et le bouton a reçu un contour.
  4. Une requête par page. Dans l'onglet Network, fais défiler jusqu'en bas. Chez nous, 36 pins sont arrivés en deux requêtes (cursor=12 et cursor=24), sans doublon, même si en mode développement React exécute les effets deux fois. Une erreur typique de l'agent est setPins([...pins, ...nouveaux]) dans un effet au tableau de dépendances vide : la fermeture voit toujours la première page, et un indicateur de chargement dans l'état n'arrête pas le deuxième appel. Symptôme : les mêmes pins en double et un avertissement sur des clés répétées.

Étape suivante

Quand la revue passe, demande un commit "Grille masonry avec défilement infini". Puis une petite étape : "Quand le chargement d'une page échoue, affiche un bouton Réessayer". Dans la leçon suivante, le bouton Enregistrer recevra des coffres. Dans l'éditeur ci-dessous t'attend la répartition en colonnes en miniature : ajoute les pins un par un, change le nombre de colonnes et regarde laquelle est la plus basse.

Retiens ceci : un bon quartier-maître pose chaque caisse sur la pile la plus basse et compte les piles d'après la liste de chargement, au lieu de réécrire le registre pendant qu'il compte.

Code de cette leçon : App.tsx
// Masonry en miniature : ajoute les pins un par un et regarde quelle colonne est la plus basse
import { useState } from 'react';

interface Pin {
  id: string;
  title: string;
  width: number;
  height: number;
  dominantColor: string;
}

const PINS: Pin[] = [
  { id: 'p1', title: 'Crique à l’aube', width: 600, height: 400, dominantColor: '#289888' },
  { id: 'p2', title: 'Coucher de soleil sur le port', width: 600, height: 900, dominantColor: '#f8a858' },
  { id: 'p3', title: 'Jungle sur l’île', width: 600, height: 750, dominantColor: '#284858' },
  { id: 'p4', title: 'Sable sous le palmier', width: 600, height: 600, dominantColor: '#e8c868' },
  { id: 'p5', title: 'Les abysses', width: 600, height: 1050, dominantColor: '#487898' },
  { id: 'p6', title: 'Récif corallien', width: 600, height: 500, dominantColor: '#e86868' },
  { id: 'p7', title: 'Lagon', width: 600, height: 800, dominantColor: '#a8c808' },
  { id: 'p8', title: 'Or dans le coffre', width: 600, height: 450, dominantColor: '#f88808' },
  { id: 'p9', title: 'Quart de nuit', width: 600, height: 1200, dominantColor: '#080858' },
  { id: 'p10', title: 'Vieille carte', width: 600, height: 700, dominantColor: '#986848' },
  { id: 'p11', title: 'Pont en bois', width: 600, height: 950, dominantColor: '#785838' },
  { id: 'p12', title: 'Pavillon dans le port', width: 600, height: 550, dominantColor: '#d8a898' },
];

// La fonction pure de la leçon : colonnes et hauteurs calculées pendant le rendu, sans état
function distributePins(pins: readonly Pin[], columnCount: number) {
  const columns: Pin[][] = Array.from({ length: columnCount }, () => []);
  const heights: number[] = new Array(columnCount).fill(0);
  for (const pin of pins) {
    const shortest = heights.indexOf(Math.min(...heights));
    columns[shortest].push(pin);
    heights[shortest] += pin.height / pin.width; // hauteur pour une colonne de largeur 1
  }
  return { columns, heights };
}

export default function App() {
  const [placed, setPlaced] = useState(3);
  const [columnCount, setColumnCount] = useState(3);

  const { columns, heights } = distributePins(PINS.slice(0, placed), columnCount);
  const next = PINS[placed];
  const shortest = heights.indexOf(Math.min(...heights));
  const lastId = PINS[placed - 1]?.id;

  return (
    <div className="min-h-screen bg-amber-50 p-4 text-zinc-900">
      <h1 className="text-xl font-bold">Carte au trésor en colonnes</h1>
      <div className="my-3 flex flex-wrap items-center gap-2">
        <button
          type="button"
          onClick={() => setPlaced((n) => Math.min(n + 1, PINS.length))}
          disabled={!next}
          className="rounded-full bg-red-600 px-4 py-2 font-semibold text-white disabled:bg-zinc-400"
        >
          Ajouter un pin
        </button>
        <button type="button" onClick={() => setPlaced(0)} className="rounded-full bg-zinc-200 px-4 py-2">
          Recommencer
        </button>
        <label className="flex items-center gap-2">
          Colonnes :
          <select value={columnCount} onChange={(e) => setColumnCount(Number(e.target.value))} className="rounded border border-zinc-300 px-2 py-1">
            <option value={2}>2 (téléphone)</option>
            <option value={3}>3 (dès 768 px)</option>
            <option value={4}>4 (dès 1024 px)</option>
          </select>
        </label>
      </div>
      <p role="status" className="mb-3 text-sm">
        {next
          ? 'Le pin suivant "' + next.title + '" (proportion ' + (next.height / next.width).toFixed(2) + ') ira dans la colonne ' + (shortest + 1) + '.'
          : 'Tous les pins sont déjà sur la carte.'}
      </p>
      <div className="flex items-start gap-3">
        {columns.map((column, c) => (
          <div key={c} className="min-w-0 flex-1">
            <p className={c === shortest ? 'mb-1 text-xs font-bold text-red-700' : 'mb-1 text-xs text-zinc-500'}>
              Colonne {c + 1} : {heights[c].toFixed(2)}
              {c === shortest && next ? ' (la plus basse)' : ''}
            </p>
            <ul className="flex flex-col gap-2">
              {column.map((pin) => (
                <li
                  key={pin.id}
                  style={{ aspectRatio: pin.width + ' / ' + pin.height, backgroundColor: pin.dominantColor }}
                  className={pin.id === lastId ? 'flex items-end rounded-xl p-2 ring-4 ring-red-600' : 'flex items-end rounded-xl p-2'}
                >
                  <span className="rounded bg-black/50 px-1 text-xs text-white">{pin.title}</span>
                </li>
              ))}
            </ul>
          </div>
        ))}
      </div>
      <p className="mt-4 text-sm text-zinc-600">
        Change le nombre de colonnes : la répartition est recalculée à partir de la même liste, car c’est le résultat d’une fonction, pas un état.
      </p>
    </div>
  );
}

Tu as repéré une erreur dans cette leçon ?

Teste tes connaissances

Réponds aux questions de cette leçon. Choisis une réponse pour voir tout de suite si elle est correcte.

  1. 1. Tu donnes à Claude le croquis croquis/masonry.png. Que le croquis ne dira pas, et qui doit donc figurer dans le texte de la demande ?

  2. 2. En quoi la disposition masonry diffère-t-elle d'une grille ordinaire en rangées ?

Voici 2 des 8 questions de cette leçon. Réponds aux autres dans le jeu.

Tâches pratiques dans le jeu

  • Tri horizontal

    Ordonne la ligne de distributePins qui trouve le numéro de la colonne la plus basse :

  • Tri vertical

    Ordonne les lignes de la boucle qui répartit les pins entre les colonnes :

  • Éditeur de code

    Crée une disposition en maçonnerie pour les pins

  • Tri horizontal

    Ordonne la ligne de MasonryGrid qui calcule les colonnes pendant le rendu, sans état :

  • Clique dans l'ordre

    Clique sur les éléments pour construire l'appel de useColumnCount :

  • Éditeur de code

    Construis une carte de pin avec des effets au survol

  • Tri vertical

    Ordonne ce qui se passe dans PinFeed quand le spectateur approche de la fin de la liste :

  • Clique dans l'ordre

    Clique sur les éléments pour construire la ligne qui demande à l'observateur de surveiller la sentinelle :

  • Tri horizontal

    Ordonne la ligne qui ajoute les nouveaux pins à la liste la plus récente, et non à une ancienne valeur de la fermeture :

  • Clique dans l'ordre

    Clique sur les éléments pour construire le calcul de la hauteur la plus basse des colonnes :

  • Tri vertical

    Ordonne les couches de PinCard, du fond (dessous) au dessus :

  1. QuestionQuiz : Le croquis comme entrée
  2. QuestionQuiz : La disposition masonry
  3. QuestionQuiz : Les champs width et height du pin
  4. Remets dans l'ordreTri : Numéro de la colonne la plus basse
  5. Remets dans l'ordreTri : La boucle distributePins
  6. Exercice de codePratique : Grille en maçonnerie
  7. QuestionQuiz : La proportion plutôt que les pixels
  8. QuestionQuiz : Le voile de la carte du pin
  9. Remets dans l'ordreTri : Répartition calculée dans le rendu
  10. Clique dans l'ordreConstruction : Nombre de colonnes sans erreur d'hydratation
  11. Exercice de codePratique : Carte de pin
  12. QuestionQuiz : La sentinelle du défilement infini
  13. Remets dans l'ordreTri : Chargement d'une page de pins
  14. Clique dans l'ordreConstruction : observer.observe(sentinel)
  15. QuestionQuiz : État modifié pendant le rendu
  16. Remets dans l'ordreTri : Ajouter les pins à la liste la plus récente
  17. QuestionQuiz : La couleur dominante avant le chargement
  18. Clique dans l'ordreConstruction : Math.min pour les colonnes
  19. Remets dans l'ordreTri : Les couches de la carte du pin

Articles utiles