[Nom du Composant]

[Nom du Composant]

Documentation technique

Type de ressource : Composant Astro (UI atomique / Îlot interactif)
Fichier source : src/components/[ui|interactive]/[NomComposant].astro
Statut : [Actif / Déprécié / En développement]
Slice : [Numéro de la tranche verticale]
Version : 1.0

1. Vue d’ensemble (DOC)

1.1. Description

[Description concise du rôle de ce composant dans l’interface utilisateur]

1.2. Objectif

• [Objectif principal : ex. afficher un bouton d’action réutilisable]
• [Bénéfice pour l’UX ou l’architecture]

1.3. Caractéristiques

Propriété	Valeur
Type	[UI atomique / Îlot interactif]
Hydratation	[Aucune / client:load / client:visible / client:idle]
Framework JS	[Aucun / React / Vue / Svelte / Web Component]
Accessibilité	[WCAG AA conforme / Partiellement conforme / Non testé]
Responsive	[Mobile-first / Desktop-first]

2. Architecture et structure (DOC)

2.1. Emplacement dans l’arborescence

src/components/
├── ui/                      # Composants atomiques (HTML + CSS purs)
│   ├── Button.astro
│   ├── Badge.astro
│   └── [NomComposant].astro
└── interactive/             # Îlots dynamiques (React/Vue/Svelte)
    ├── MobileNav.tsx
    ├── Carousel.tsx
    └── [NomComposant].tsx

2.2. Composants dépendants

Composant parent	Fichier	Relation
[Nom du parent]	src/components/[chemin]	[Composition / Wrapper]

2.3. Composants enfants utilisés

Composant enfant	Fichier	Rôle
[Nom de l’enfant]	src/components/[chemin]	[Description]

3. Implémentation (CODE)

3.1. Variante : Composant UI atomique (HTML + CSS purs)1/2

3.1. Variante : Composant UI atomique (HTML + CSS purs)2/2

src/components/ui/[NomComposant].astro

---
interface Props {
  label: string;
  variant?: 'primary' | 'secondary' | 'outline';
  size?: 'sm' | 'md' | 'lg';
  disabled?: boolean;
  href?: string;
  onClick?: () => void;
}

const {
  label,
  variant = 'primary',
  size = 'md',
  disabled = false,
  href,
  onClick,
} = Astro.props;

const baseClasses = 'inline-flex items-center justify-center font-medium rounded-lg transition-colors focus:outline-none focus:ring-2 focus:ring-offset-2';

const variantClasses = {
  primary: 'bg-blue-600 text-white hover:bg-blue-700 focus:ring-blue-500',
  secondary: 'bg-gray-600 text-white hover:bg-gray-700 focus:ring-gray-500',
  outline: 'border-2 border-blue-600 text-blue-600 hover:bg-blue-50 focus:ring-blue-500',
};

const sizeClasses = {
  sm: 'px-3 py-1.5 text-sm',
  md: 'px-4 py-2 text-base',
  lg: 'px-6 py-3 text-lg',
};

const classes = `${baseClasses} ${variantClasses[variant]} ${sizeClasses[size]} ${disabled ? 'opacity-50 cursor-not-allowed' : ''}`;
---

{href ? (
  <a
    href={href}
    class={classes}
    aria-disabled={disabled}
  >
    {label}
  </a>
) : (
  <button
    class={classes}
    disabled={disabled}
    onClick={onClick}
  >
    {label}
  </button>
)}

3.2. Variante : Îlot interactif (React)

src/components/interactive/[NomComposant].tsx

import { useState } from 'react';

interface Props {
  initialValue?: number;
}

export default function Counter({ initialValue = 0 }: Props) {
  const [count, setCount] = useState(initialValue);

  return (
    <div class="flex items-center gap-4">
      <button onClick={() => setCount(c => c - 1)}>-</button>
      <span>{count}</span>
      <button onClick={() => setCount(c => c + 1)}>+</button>
    </div>
  );
}

4. Contrats d’Entrée/Sortie (SPEC)

4.1. Inputs (Props)

Prop	Type	Obligatoire	Validation
label	string	✅	Non vide
variant	enum	❌	Valeur par défaut
size	enum	❌	Valeur par défaut

4.2. Outputs (Rendu)

Élément	Type	Description
HTML	HTMLElement	Composant rendu
Événements	Event	onClick, onChange, etc.

4.3. États (si interactif)

État	Type	Description
count	number	Valeur du compteur

5. Tests attendus (TEST)

5.1. Tests unitaires

Scénario	Description	Résultat attendu
Rendu avec props	Props valides	Composant rendu correctement
Accessibilité	Test ARIA	Conforme WCAG AA
Responsive	Test mobile/desktop	Adaptation correcte

5.2. Tests d’intégration

Scénario	Dépendances	Description	Résultat attendu
Intégration parent	Composant parent	Utilisation dans une page	Fonctionne correctement

5.3. Tests E2E

Scénario	Parcours utilisateur	Description	Résultat attendu
Interaction utilisateur	Clic / Interaction	Action utilisateur	Réponse attendue

6. Intégration (INTÉG)

6.1. Intégration avec les composants

Composant	Type	Rôle	Méthode d’intégration
Page parent	L2	Utilisation du composant	Import et rendu
Layout	L2	Inclusion globale	Import dans layout

6.2. Points d’attention

• Les props doivent être typées avec TypeScript
• L’accessibilité doit être conforme WCAG AA
• Le composant doit être responsive

6.3. Vérification de cohérence

• Le composant fonctionne en isolation
• Le composant s’intègre correctement avec les parents
• Les tests d’accessibilité passent
• Les tests E2E passent

7. Sécurité

7.1. Mécanismes de sécurité

• ✅ Validation des props
• ✅ Protection XSS (Astro par défaut)
• ✅ Sanitization du contenu utilisateur

7.2. Règles de sécurité

• ✅ Ne jamais exécuter de code utilisateur non sécurisé
• ✅ Valider toutes les entrées
• ✅ Utiliser les attributs ARIA appropriés

8. Performance et limites

8.1. Hydratation

Directive	Description
client:load	Hydratation immédiate
client:visible	Hydratation quand visible
client:idle	Hydratation quand le navigateur est inactif

8.2. Limitations

• ❌ Les îlots interactifs augmentent le bundle size
• ❌ L’hydratation peut affecter le LCP

9. Débogage et troubleshooting

9.1. Problèmes courants

Symptôme	Cause probable	Solution
Composant non rendu	Props manquantes	Vérifier les props
Hydratation échoue	Erreur JavaScript	Vérifier la console
Accessibilité échoue	ARIA manquant	Ajouter les attributs

9.2. Commandes de debug

# Lancer les tests
npm run test

# Lancer les tests E2E
npm run test:e2e

10. Bonnes pratiques

10.1. Architecture

• ✅ Composants atomiques réutilisables
• ✅ Props typées avec TypeScript
• ✅ Accessibilité par défaut

10.2. Code

• ✅ Utiliser les classes Tailwind pour le style
• ✅ Éviter les effets de bord
• ✅ Documenter les props complexes

10.3. Maintenance

• ✅ Documenter les changements dans ce fichier
• ✅ Tester les modifications en local

11. Évolutions et roadmap

11.1. Améliorations planifiées

• [Évolution 1]
• [Évolution 2]

11.2. Limitations connues

• ❌ [Limitation 1]
• ❌ [Limitation 2]

12. Ressources liées

• Documentation Astro : Components
• Documentation Astro : Islands
• DAT L2 : §5.4 - Stratégie d’Hydratation

13. Historique des modifications

Date	Version	Description	Auteur
YYYY-MM-DD	1.0	Création initiale	[Nom]

Switch to normal mode

ContentsSpeaker viewToggle fullscreenExport as PDF

Contents

Close

[Nom du Composant]

1. 1. Vue d’ensemble (DOC)3
2. 1.1. Description4
3. 1.2. Objectif5
4. 1.3. Caractéristiques6
5. 2. Architecture et structure (DOC)7
6. 2.1. Emplacement dans l’arborescence8
7. 2.2. Composants dépendants9
8. 2.3. Composants enfants utilisés10
9. 3. Implémentation (CODE)11
10. 3.1. Variante : Composant UI atomique (HTML + CSS purs)12
11. 3.2. Variante : Îlot interactif (React)14
12. 4. Contrats d’Entrée/Sortie (SPEC)15
13. 4.1. Inputs (Props)16
14. 4.2. Outputs (Rendu)17
15. 4.3. États (si interactif)18
16. 5. Tests attendus (TEST)19
17. 5.1. Tests unitaires20
18. 5.2. Tests d’intégration21
19. 5.3. Tests E2E22
20. 6. Intégration (INTÉG)23
21. 6.1. Intégration avec les composants24
22. 6.2. Points d’attention25
23. 6.3. Vérification de cohérence26
24. 7. Sécurité27
25. 7.1. Mécanismes de sécurité28
26. 7.2. Règles de sécurité29
27. 8. Performance et limites30
28. 8.1. Hydratation31
29. 8.2. Limitations32
30. 9. Débogage et troubleshooting33
31. 9.1. Problèmes courants34
32. 9.2. Commandes de debug35
33. 10. Bonnes pratiques36
34. 10.1. Architecture37
35. 10.2. Code38
36. 10.3. Maintenance39
37. 11. Évolutions et roadmap40
38. 11.1. Améliorations planifiées41
39. 11.2. Limitations connues42
40. 12. Ressources liées43
41. 13. Historique des modifications44