[Nom de l'Intégration API Pagefind]

Type de ressource : API JavaScript Pagefind (Recherche programmatique)
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 intégration API dans l’architecture de recherche du site]

1.2. Objectif

• [Objectif principal : ex. fournir une recherche custom avec contrôle total sur l’UI et le comportement]
• [Bénéfice par rapport à Pagefind UI natif : ex. personnalisation complète, intégration design system]

1.3. Périmètre concerné

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

Type d’API	Statut
Pagefind JS API	[✅/❌]
Pagefind UI custom	[✅/❌]
Les deux	[✅/❌]

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

---

2. Architecture et flux (DOC)

2.1. Diagramme de flux

[Utilisateur]
     │  (saisie dans la barre de recherche)
     ▼
[Composant SearchBar (Astro)]
     │  • Import dynamique de Pagefind
     │  • Initialisation de l'index
     │  • Debounce sur l'input
     ▼
[Pagefind JS API]
     │  • Chargement de l'index chunké
     │  • Recherche côté client
     │  • Application des filtres
     ▼
[Résultats]
     │  • Extraction des métadonnées
     │  • Distinction visuelle par type
     │  • Pagination / Limitation
     ▼
[Interface custom]
     │  • Rendu des résultats
     │  • Badges (Doc, Blog, Portfolio, Page)
     ▼
[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 JS API	Bibliothèque JS de recherche	pagefind (npm)
Index Pagefind	Index chunké généré au build	dist/_pagefind/

---

3. Implémentation de l’API Pagefind (CODE)

3.1. Import et initialisation

src/components/ui/SearchBar.astro

<div class="search-container" data-pagefind-ignore="all">
  <input
    type="search"
    id="search-input"
    placeholder="Rechercher..."
    class="search-input"
    autocomplete="off"
    aria-label="Rechercher dans le site"
  />

  <div id="search-results" role="region" aria-label="Résultats de recherche" aria-live="polite">
    <!-- Résultats injectés dynamiquement -->
  </div>
</div>

<script>
  // Import dynamique de Pagefind (lazy loading)
  let pagefind: any = null;

  async function initPagefind() {
    if (pagefind) return;

    // Import dynamique pour éviter de charger Pagefind au chargement initial
    // @ts-ignore
    pagefind = await import('/pagefind/pagefind.js');
    await pagefind.init();
  }

  // Initialisation au premier focus
  const searchInput = document.getElementById('search-input');
  searchInput?.addEventListener('focus', initPagefind);
</script>

3.2. Recherche avec filtres

// Fonction de recherche avec filtres
async function search(query: string, filters?: { type?: string }) {
  if (!pagefind) await initPagefind();

  const results = await pagefind.search(query, {
    filter: (result) => {
      if (filters?.type) {
        return result.meta?.type === filters.type;
      }
      return true;
    },
  });

  return results;
}

---

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

4.1. Inputs (Requête de recherche)

Paramètre	Type	Validation
query	string	Non vide
filters	object	Filtres valides

4.2. Outputs (Résultats)

Élément	Type	Description
results	array	Liste des résultats
meta	object	Métadonnées

---

5. Tests attendus (TEST)

5.1. Tests unitaires

Scénario	Description	Résultat attendu
Initialisation	Premier focus	Pagefind chargé
Recherche	Terme valide	Résultats retournés
Filtres	Filtre appliqué	Résultats filtrés

5.2. Tests d’intégration

Scénario	Dépendances	Description	Résultat attendu
Flux complet	Index + API	Recherche → Résultats	Résultats affichés

---

6. Intégration (INTÉG)

6.1. Intégration avec les composants

Composant	Type	Rôle	Méthode d’intégration
SearchBar	L2	Interface	Composant Astro
Index	Build	Données	Pagefind CLI

6.2. Points d’attention

• L’import doit être dynamique (lazy loading)
• Le debounce doit être configuré
• Les filtres doivent être cohérents avec les métadonnées

6.3. Vérification de cohérence

• L’API est initialisée correctement
• Les résultats sont pertinents
• Les filtres fonctionnent
• Les tests E2E passent

---

7. Sécurité

7.1. Mécanismes de sécurité

• ✅ Pas d’exposition de données sensibles
• ✅ Validation des entrées

7.2. Règles de sécurité

• ✅ Sanitization des requêtes
• ✅ Limite de résultats

---

8. Performance et limites

8.1. Limites

Limite	Valeur
Taille de l’index	~10 MB
Temps de chargement	~1s

8.2. Optimisations

• ✅ Lazy loading
• ✅ Debounce
• ✅ Pagination

---

9. Débogage et troubleshooting

9.1. Problèmes courants

Symptôme	Cause probable	Solution
Pagefind non chargé	Import échoué	Vérifier le chemin
Résultats vides	Index vide	Vérifier le build

9.2. Commandes de debug

# Build local
npm run build

# Preview
npm run preview

---

10. Bonnes pratiques

10.1. Architecture

• ✅ Lazy loading de Pagefind
• ✅ Debounce sur l’input
• ✅ Filtres cohérents

10.2. Code

• ✅ TypeScript strict
• ✅ Gestion des erreurs
• ✅ Accessibilité

---

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 : API Reference

---

13. Historique des modifications

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