Compétence Composant Frontend
Objectif : Fournir des directives pour la création de composants Next.js respectant les modèles serveur/client et les structures de composants existantes.
Aperçu
Next.js 16+ utilise le App Router avec les composants serveur par défaut. Les composants client ne sont utilisés que lorsque l'interactivité est nécessaire (hooks, gestionnaires d'événements, API navigateur).
Composants Serveur vs Client
Composants Serveur (Par défaut)
Quand les utiliser :
- Pages et layouts
- Contenu statique
- Récupération de données depuis l'API (quand c'est possible)
- Contenu optimisé pour le SEO
Modèle :
// Pas de directive "use client"
import { Metadata } from "next";
export const metadata: Metadata = {
title: "Titre de la page",
};
export default function PageComponent() {
return <div>Contenu statique</div>;
}
Exemple : frontend/app/layout.tsx, frontend/app/page.tsx
Composants Client (Quand nécessaire)
Quand les utiliser :
- Éléments interactifs (boutons, formulaires, champs de saisie)
- Gestionnaires d'événements (onClick, onChange, etc.)
- Hooks React (useState, useEffect, useRouter, etc.)
- API navigateur (localStorage, window, document, etc.)
- Mises à jour en temps réel
- Fonctionnalités de glisser-déposer
Modèle :
"use client"; // DOIT être la première ligne
import { useState, useEffect } from "react";
import { useRouter } from "next/navigation";
interface ComponentProps {
prop1: string;
prop2?: number;
}
export default function NomDuComposant({ prop1, prop2 }: ComponentProps) {
const router = useRouter();
const [state, setState] = useState("");
useEffect(() => {
// Effets de bord
}, []);
return <div>{/* JSX du composant */}</div>;
}
Exemple : frontend/components/ProtectedRoute.tsx, frontend/app/signup/page.tsx
Modèle de Structure de Composant
"use client"; // Uniquement si composant client
/**
* Nom du Composant
*
* Brève description de ce que fait ce composant
*/
import { useState, useEffect } from "react";
import { ComponentType } from "@/types";
import { cn } from "@/lib/utils";
interface ComponentProps {
prop1: string;
prop2?: number;
className?: string;
}
export default function NomDuComposant({ prop1, prop2, className }: ComponentProps) {
// État
const [state, setState] = useState("");
// Effets
useEffect(() => {
// Effets de bord
}, []);
// Gestionnaires
const handleClick = () => {
// Logique du gestionnaire
};
// Rendu
return (
<div className={cn("classes-de-base", className)}>
{/* Contenu du composant */}
</div>
);
}
Modèles de Composants Spécifiques
1. Modèle ProtectedRoute
Depuis : frontend/components/ProtectedRoute.tsx
"use client";
import { useEffect, useState } from "react";
import { useRouter } from "next/navigation";
import { isAuthenticated } from "@/lib/auth";
import LoadingSpinner from "./LoadingSpinner";
interface ProtectedRouteProps {
children: React.ReactNode;
}
export default function ProtectedRoute({ children }: ProtectedRouteProps) {
const router = useRouter();
const [isAuthorized, setIsAuthorized] = useState(false);
const [isChecking, setIsChecking] = useState(true);
useEffect(() => {
async function checkAuth() {
try {
const authenticated = await isAuthenticated();
if (!authenticated) {
const currentPath = window.location.pathname;
if (currentPath !== "/signin") {
sessionStorage.setItem("redirectAfterLogin", currentPath);
}
router.push("/signin");
} else {
setIsAuthorized(true);
}
} catch (error) {
console.error("La vérification d'authentification a échoué :", error);
router.push("/signin");
} finally {
setIsChecking(false);
}
}
checkAuth();
}, [router]);
if (isChecking) {
return (
<div className="min-h-screen flex items-center justify-center">
<LoadingSpinner size="large" />
</div>
);
}
if (!isAuthorized) {
return null;
}
return <>{children}</>;
}
Modèle :
- Vérifier l'authentification au montage
- Afficher un indicateur de chargement pendant la vérification
- Stocker la destination prévue dans sessionStorage
- Rediriger vers
/signinsi non authentifié - Ne rendre les enfants que si autorisé
2. Modèle LoadingSpinner
Depuis : frontend/components/LoadingSpinner.tsx
interface LoadingSpinnerProps {
size?: "small" | "medium" | "large";
color?: string;
label?: string;
}
export default function LoadingSpinner({
size = "medium",
color = "blue",
label = "Chargement...",
}: LoadingSpinnerProps) {
const sizeClasses = {
small: "w-4 h-4 border-2",
medium: "w-8 h-8 border-3",
large: "w-12 h-12 border-4",
};
const colorClasses = {
blue: "border-blue-600 border-t-transparent",
gray: "border-gray-600 border-t-transparent",
white: "border-white border-t-transparent",
};
const spinnerClass = `${sizeClasses[size]} ${
colorClasses[color as keyof typeof colorClasses] || colorClasses.blue
} rounded-full animate-spin`;
return (
<div
className="flex items-center justify-center"
role="status"
aria-label={label}
aria-live="polite"
>
<div className={spinnerClass}></div>
<span className="sr-only">{label}</span>
</div>
);
}
Modèle :
- Tailles multiples (petite, moyenne, grande)
- Couleurs multiples (bleu, gris, blanc)
- Labels d'accessibilité (
role="status",aria-label,aria-live) - Texte pour lecteurs d'écran avec la classe
sr-only
3. Modèle de Gestion de Formulaire
Depuis : frontend/app/signup/page.tsx
"use client";
import { useState } from "react";
import { useRouter } from "next/navigation";
import { api } from "@/lib/api";
import { isValidEmail, getPasswordStrength } from "@/lib/utils";
export default function SignupPage() {
const router = useRouter();
const [formData, setFormData] = useState({
name: "",
email: "",
password: "",
});
const [errors, setErrors] = useState<Record<string, string>>({});
const [isLoading, setIsLoading] = useState(false);
const [apiError, setApiError] = useState("");
const validateForm = (): boolean => {
const newErrors: Record<string, string> = {};
if (!formData.name.trim()) {
newErrors.name = "Le nom est requis";
}
if (!formData.email.trim()) {
newErrors.email = "L'email est requis";
} else if (!isValidEmail(formData.email)) {
newErrors.email = "Veuillez entrer une adresse email valide";
}
// Plus de validation...
setErrors(newErrors);
return Object.keys(newErrors).length === 0;
};
const handleSubmit = async (e: React.FormEvent) => {
e.preventDefault();
setApiError("");
if (!validateForm()) {
return;
}
setIsLoading(true);
try {
const response = await api.signup(formData);
if (response.success) {
router.push("/dashboard");
} else {
setApiError(response.message || "L'inscription a échoué");
}
} catch (error: any) {
setApiError(error.message || "Une erreur est survenue");
} finally {
setIsLoading(false);
}
};
const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
const { name, value } = e.target;
setFormData((prev) => ({ ...prev, [name]: value }));
// Effacer l'erreur pour ce champ quand l'utilisateur commence à taper
if (errors[name]) {
setErrors((prev) => ({ ...prev, [name]: "" }));
}
};
return (
<form onSubmit={handleSubmit}>
{/* Champs du formulaire */}
</form>
);
}
Modèle :
- État séparé pour les données du formulaire, les erreurs, le chargement, les erreurs API
- Fonction de validation qui retourne un booléen
- Effacer les erreurs lors de la saisie
- État de chargement pendant la soumission
- Try-catch pour la gestion des erreurs
- Redirection en cas de succès
4. Modèle ToastNotification
Depuis : frontend/components/ToastNotification.tsx
"use client";
import { useEffect, useState } from "react";
import { ToastMessage, ToastType } from "@/types";
export function useToast() {
const [toasts, setToasts] = useState<ToastMessage[]>([]);
const showToast = (type: ToastType, message: string, duration?: number) => {
const id = `toast-${Date.now()}-${Math.random()}`;
const newToast: ToastMessage = {
id,
type,
message,
duration,
};
setToasts((prev) => [...prev, newToast]);
};
const dismissToast = (id: string) => {
setToasts((prev) => prev.filter((toast) => toast.id !== id));
};
return {
toasts,
showToast,
dismissToast,
success: (message: string, duration?: number) => showToast("success", message, duration),
error: (message: string, duration?: number) => showToast("error", message, duration),
// ...
};
}
Modèle :
- Hook personnalisé pour la gestion des notifications
- Fermeture automatique avec durée
- Empiler plusieurs notifications
- Méthodes d'aide (succès, erreur, avertissement, info)
Modèles Tailwind CSS
1. Classes Utilitaires Uniquement
<div className="flex items-center justify-center gap-4 p-6 bg-white rounded-lg shadow-md">
Modèle : Utiliser les classes utilitaires Tailwind, pas de styles en ligne
2. Classes Conditionnelles avec la Fonction cn()
import { cn } from "@/lib/utils";
<div className={cn(
"classes-de-base",
condition && "classes-conditionnelles",
className // Permettre la surcharge via les props
)}>
Modèle : Utiliser cn() depuis @/lib/utils pour les classes conditionnelles
3. Support du Mode Sombre
<div className="bg-white dark:bg-gray-800 text-gray-900 dark:text-white">
Modèle : Utiliser le préfixe dark: pour les styles en mode sombre
4. Design Responsive
<div className="w-full sm:w-1/2 md:w-1/3 lg:w-1/4">
Modèle : Utiliser les préfixes de points de rupture (sm:, md:, lg:, xl:)
Modèles d'Accessibilité (WCAG 2.1 AA)
1. Labels ARIA
<button aria-label="Fermer la boîte de dialogue">×</button>
<div role="status" aria-live="polite" aria-label="Chargement...">
Modèle : Toujours fournir un aria-label pour les boutons avec uniquement une icône
2. HTML Sémantique
<nav>
<ul>
<li><a href="/">Accueil</a></li>
</ul>
</nav>
Modèle : Utiliser des éléments HTML sémantiques (nav, main, section, article, etc.)
3. Navigation au Clavier
<button
onClick={handleClick}
onKeyDown={(e) => {
if (e.key === "Enter" || e.key === " ") {
handleClick();
}
}}
>
Modèle : Assurer l'accessibilité clavier pour tous les éléments interactifs
4. Texte pour Lecteurs d'Écran
<span className="sr-only">Chargement du contenu</span>
Modèle : Utiliser la classe sr-only pour le texte réservé aux lecteurs d'écran
5. Gestion du Focus
<input
autoFocus
className="focus:outline-none focus:ring-2 focus:ring-blue-500"
/>
Modèle : Toujours fournir des indicateurs de focus visibles
Conventions de Nommage des Fichiers
- Pages : kebab-case (par ex.,
signup.tsx,signin.tsx) - Composants : PascalCase (par ex.,
TaskList.tsx,TaskItem.tsx) - Layouts :
layout.tsx - Pages d'Erreur :
error.tsx,not-found.tsx
Exigences de la Constitution
- FR-033 : Structure du App Router Next.js 16+ ✅
- FR-034 : Composants serveur par défaut, client si nécessaire ✅
- FR-035 : Limites d'erreur ✅
- FR-036 : Conformité WCAG 2.1 AA ✅
- FR-037 : Mode strict TypeScript ✅
- FR-038 : Formatage Prettier ✅
- FR-039 : Règles ESLint ✅
Références
- Spécification :
specs/002-frontend-todo-app/spec.md- Spécifications des composants - Composants Existants :
frontend/components/*.tsx- Exemples de composants - Pages Existantes :
frontend/app/*.tsx- Exemples de pages
Modèles de Composants Avancés
1. Modèle Glisser-Déposer (Phase 7 - T065)
Bibliothèque : @dnd-kit/core
"use client";
import { DndContext, closestCenter, KeyboardSensor, PointerSensor, useSensor, useSensors } from "@dnd-kit/core";
import { SortableContext, sortableKeyboardCoordinates, useSortable, verticalListSortingStrategy } from "@dnd-kit/sortable";
export default function SortableTaskList({ tasks, onReorder }: Props) {
const sensors = useSensors(
useSensor(PointerSensor),
useSensor(KeyboardSensor, {
coordinateGetter: sortableKeyboardCoordinates,
})
);
const handleDragEnd = (event: DragEndEvent) => {
const { active, over } = event;
if (over && active.id !== over.id) {
onReorder(active.id, over.id);
}
};
return (
<DndContext sensors={sensors} collisionDetection={closestCenter} onDragEnd={handleDragEnd}>
<SortableContext items={tasks.map(t => t.id)} strategy={verticalListSortingStrategy}>
{tasks.map(task => (
<SortableTaskItem key={task.id} task={task} />
))}
</SortableContext>
</DndContext>
);
}
Modèle : Utiliser @dnd-kit/core pour le glisser-déposer, gérer le réordonnancement à la fin du glisser
2. Modèle Undo/Redo (Phase 7 - T066)
"use client";
import { useReducer } from "react";
interface HistoryState<T> {
past: T[];
present: T;
future: T[];
}
function historyReducer<T>(state: HistoryState<T>, action: { type: string; newPresent?: T }): HistoryState<T> {
const { past, present, future } = state;
switch (action.type) {
case "UNDO":
if (past.length === 0) return state;
return {
past: past.slice(0, past.length - 1),
present: past[past.length - 1],
future: [present, ...future],
};
case "REDO":
if (future.length === 0) return state;
return {
past: [...past, present],
present: future[0],
future: future.slice(1),
};
case "SET":
if (action.newPresent === present) return state;
return {
past: [...past, present],
present: action.newPresent!,
future: [],
};
default:
return state;
}
}
export function useHistory<T>(initialPresent: T) {
const [state, dispatch] = useReducer(historyReducer, {
past: [],
present: initialPresent,
future: [],
});
const undo = () => dispatch({ type: "UNDO" });
const redo = () => dispatch({ type: "REDO" });
const set = (newPresent: T) => dispatch({ typ
…
[tronqué pour la traduction]