Composants PageBuilder

Objet : Composants Astro PageBuilder
Type : Composants
Slice : Slice 1 (Page d’accueil)
Cycle : DOC → SPEC → CODE → TEST → INTÉG
Statut : INTÉG

---

1. Description et périmètre

1.1. Objectif

Les composants PageBuilder sont des composants Astro qui rendent les différents blocs de contenu définis dans le schéma Sanity page. Chaque composant correspond à un type de bloc PageBuilder.

1.2. Utilisation principale

• Page d’accueil
• Pages marketing (landing pages)
• Pages de présentation

1.3. Périmètre concerné

• Type : Composants Astro
• Blocs implémentés : hero, features, testimonials, cta, richText, imageGallery
• Source des données : Sanity (via GROQ queries)
• Rendu : Server-side rendering

---

2. Contrats d’entrée

2.1. Props des composants

Entrée : Props passées aux composants

Structure commune :

interface PageBuilderBlock {
  _type: string;
  _key: string;
}

Props spécifiques par bloc :

Hero

interface HeroBlock extends PageBuilderBlock {
  _type: 'hero';
  heading: string;
  subheading?: string;
  ctaText?: string;
  ctaLink?: string;
  image?: {
    asset: {
      _ref: string;
    };
  };
}

Features

interface FeaturesBlock extends PageBuilderBlock {
  _type: 'features';
  heading?: string;
  features: Array<{
    title: string;
    description: string;
    icon?: string;
  }>;
}

Testimonials

interface TestimonialsBlock extends PageBuilderBlock {
  _type: 'testimonials';
  heading?: string;
  testimonials: Array<{
    name: string;
    role?: string;
    quote: string;
    avatar?: {
      asset: {
        _ref: string;
      };
    };
  }>;
}

CTA

interface CTABlock extends PageBuilderBlock {
  _type: 'cta';
  heading: string;
  description?: string;
  buttonText: string;
  buttonLink: string;
}

RichText

interface RichTextBlock extends PageBuilderBlock {
  _type: 'richText';
  content: any[]; // Portable Text
}

ImageGallery

interface ImageGalleryBlock extends PageBuilderBlock {
  _type: 'imageGallery';
  heading?: string;
  images: Array<{
    asset: {
      _ref: string;
    };
    alt?: string;
    caption?: string;
  }>;
}

2.2. Règles de validation

Règles générales :

• Tous les blocs ont _type et _key
• Les champs obligatoires doivent être présents
• Les champs optionnels peuvent être absents
• Les références d’images Sanity sont valides

---

3. Contrats de sortie

3.1. Structure HTML

Sortie : Structure HTML pour chaque bloc

Comportement :

• Chaque composant rend une section HTML sémantique
• Utilisation de balises appropriées (<section>, <h2>, etc.)
• Classes CSS pour le styling
• Images optimisées via Sanity

3.2. Accessibilité

Sortie : Accessibilité respectée

Comportement :

• Attributs alt pour les images
• Structure hiérarchique des titres
• Liens avec textes descriptifs
• ARIA labels si nécessaire

---

4. Side effects

4.1. Impact sur le rendu

Effet : Les composants PageBuilder influencent le rendu de la page

Impact :

• Chaque bloc ajoute du contenu à la page
• La structure de la page dépend de l’ordre des blocs
• Le temps de chargement dépend du nombre d’images

4.2. Impact sur le SEO

Effet : Les composants influencent le SEO

Impact :

• Contenu textuel indexable
• Images avec alt text
• Structure sémantique HTML

---

5. Erreurs et gestion

5.1. Erreurs potentielles

Erreur	Cause probable	Solution
Bloc inconnu	_type non reconnu	Ignorer ou afficher erreur
Données manquantes	Champs obligatoires absents	Afficher placeholder ou erreur
Image invalide	Référence Sanity corrompue	Afficher placeholder

5.2. Codes HTTP

Non applicable (composants Astro)

---

6. Checklist de validation

Avant de passer à l’étape SPEC, vérifier :

• La structure des composants est documentée
• Les contrats d’entrée/sortie sont documentés
• Les side effects sont identifiés
• Les erreurs potentielles sont documentées

---

7. Implémentation réalisée

7.1. Fichiers créés

Répertoire : apps/web/src/components/pagebuilder/

Composants implémentés :

• Hero.astro : Section hero avec responsive design
• Features.astro : Grille CSS responsive
• Testimonials.astro : Témoignages avec avatars circulaires
• CTA.astro : Call-to-action centré
• RichText.astro : Rendu Portable Text basique
• ImageGallery.astro : Galerie d’images avec captions

7.2. Styles CSS

Chaque composant inclut des styles scoped :

• Design responsive avec media queries
• Variables CSS pour les couleurs
• Classes utilitaires pour le layout
• Optimisation mobile-first

7.3. Interfaces TypeScript

Props typées selon les schémas Sanity :

• Interfaces correspondantes aux schémas blocks
• Types optionnels pour les champs non obligatoires
• Type any pour les références Sanity (images)

---

8. Approbation

Validation requise : Confirmer que la documentation des composants PageBuilder peut passer à l’étape SPEC.

---

9. Historique des modifications

Date	Version	Description	Auteur
2026-09-16	1.0	Création initiale	Devin
2026-09-17	2.0	Implémentation des 6 composants PageBuilder	Devin