Skip to content
AMN Docs

[Nom de l'Interface de Recherche]

[Nom de l'Interface de Recherche]

Documentation technique

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é1/3

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

1.3. Périmètre concerné2/3

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

1.3. Périmètre concerné3/3

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 custom1/2

3.2. Variante : Composant custom2/2

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

Terminal window
# 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

13. Historique des modifications

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

Contents

Built with StarlightPowered by Cloudflare