[Nom de l'Interface de Recherche]

Type de ressource : Interface Utilisateur Pagefind (Barre de recherche / Résultats / Filtres)
Fichier source : src/components/ui/SearchBar.astro ou composant associé
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 cette interface de recherche dans l’expérience utilisateur]

1.2. Objectif

• [Objectif principal : ex. fournir une recherche unifiée sur l’ensemble du site]
• [Bénéfice pour l’utilisateur : ex. trouver rapidement du contenu dans le blog, le portfolio ou la documentation]

1.3. Périmètre concerné

Couverture	Statut
Vitrine	[✅/❌]
Blog	[✅/❌]
Portfolio	[✅/❌]
Documentation	[✅/❌]
Tout	[✅/❌]

Emplacement	Statut
Header global	[✅/❌]
Sidebar	[✅/❌]
Page dédiée	[✅/❌]
Modal	[✅/❌]

Type d’interface	Statut
Pagefind UI natif	[✅/❌]
Composant custom	[✅/❌]
Les deux	[✅/❌]

---

2. Architecture et flux (DOC)

2.1. Diagramme de flux

[Utilisateur]
     │  (saisie dans la barre de recherche)
     ▼
[Composant SearchBar]
     │  • Initialisation Pagefind
     │  • Chargement de l'index chunké
     │  • Recherche côté client
     ▼
[Pagefind (client-side)]
     │  • Matching des termes
     │  • Application des filtres
     │  • Ranking des résultats
     ▼
[Affichage des résultats]
     │  • Distinction visuelle par type
     │  • Badges (Doc, Blog, Portfolio, Page)
     │  • Pagination
     ▼
[Utilisateur]
     │  (clic sur un résultat)
     ▼
[Navigation vers la page]

2.2. Composants impliqués

Composant	Rôle	Fichier
SearchBar.astro	Interface de recherche globale	src/components/ui/SearchBar.astro
SearchResults.astro	Affichage des résultats	src/components/ui/SearchResults.astro
SearchFilters.astro	Filtres par type de contenu	src/components/ui/SearchFilters.astro
Pagefind UI	Bibliothèque JS de recherche	pagefind-ui (npm)
Index Pagefind	Index chunké généré au build	dist/_pagefind/

---

3. Implémentation (CODE)

3.1. Variante : Pagefind UI natif

src/components/ui/SearchBar.astro

<div id="search"></div>

<script>
  import { Search } from 'pagefind-ui';

  window.addEventListener('DOMContentLoaded', () => {
    new Search({
      element: '#search',
      pageSize: 10,
      showSubResults: true,
      showImages: false,
      processTerm: (term) => {
        // Normalisation des termes de recherche
        return term.toLowerCase().trim();
      },
      processResult: (result) => {
        // Personnalisation des résultats
        const type = result.meta?.type || 'page';
        const badge = {
          docs: 'Doc',
          blog: 'Blog',
          portfolio: 'Portfolio',
          page: 'Page',
        }[type] || 'Page';

        return {
          ...result,
          badge,
        };
      },
    });
  });
</script>

3.2. Variante : Composant custom

src/components/ui/SearchBar.astro

<div class="search-container">
  <input
    type="search"
    id="search-input"
    placeholder="Rechercher..."
    class="search-input"
  />

  <div id="search-results" class="search-results">
    <!-- Résultats injectés dynamiquement -->
  </div>
</div>

<style>
  .search-container {
    position: relative;
  }

  .search-input {
    width: 100%;
    padding: 0.5rem 1rem;
    border: 1px solid #e5e7eb;
    border-radius: 0.375rem;
  }

  .search-results {
    position: absolute;
    top: 100%;
    left: 0;
    right: 0;
    background: white;
    border: 1px solid #e5e7eb;
    border-radius: 0.375rem;
    max-height: 400px;
    overflow-y: auto;
  }
</style>

---

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

4.1. Inputs (Saisie utilisateur)

Paramètre	Type	Validation
query	string	Non vide après debounce

4.2. Outputs (Affichage)

Élément	Type	Description
results	HTMLElement	Liste des résultats
badges	HTMLElement	Badges de type

---

5. Tests attendus (TEST)

5.1. Tests unitaires

Scénario	Description	Résultat attendu
Rendu	Composant monté	Interface affichée
Input	Saisie utilisateur	Recherche déclenchée

5.2. Tests d’intégration

Scénario	Dépendances	Description	Résultat attendu
Flux complet	Index + UI	Recherche → Navigation	Résultats cliquables

---

6. Intégration (INTÉG)

6.1. Intégration avec les composants

Composant	Type	Rôle	Méthode d’intégration
Header	L2	Emplacement	Composant inclus
Index	Build	Données	Pagefind CLI

6.2. Points d’attention

• L’interface doit être accessible
• Les badges doivent être cohérents
• La pagination doit fonctionner

6.3. Vérification de cohérence

• L’interface est accessible
• Les résultats s’affichent
• Les badges sont corrects
• Les tests E2E passent

---

7. Sécurité

7.1. Mécanismes de sécurité

• ✅ Sanitization des résultats
• ✅ Protection XSS

7.2. Règles de sécurité

• ✅ Valider les entrées
• ✅ Échapper le HTML

---

8. Performance et limites

8.1. Limites

Limite	Valeur
Résultats par page	10-20
Temps de recherche	< 500ms

8.2. Optimisations

• ✅ Debounce
• ✅ Pagination
• ✅ Lazy loading

---

9. Débogage et troubleshooting

9.1. Problèmes courants

Symptôme	Cause probable	Solution
Résultats non affichés	Erreur JS	Vérifier la console
Badges incorrects	Métadonnées manquantes	Vérifier l’indexation

9.2. Commandes de debug

# Build local
npm run build

# Preview
npm run preview

---

10. Bonnes pratiques

10.1. Architecture

• ✅ Accessibilité (ARIA)
• ✅ Responsive design
• ✅ Cohérence visuelle

10.2. Code

• ✅ TypeScript strict
• ✅ Gestion des erreurs
• ✅ Documentation

---

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 Pagefind : UI Reference

---

13. Historique des modifications

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