Composants PageBuilder

Documentation technique

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

Entrée : Props passées aux composants

Structure commune :

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

Props spécifiques par bloc :

Hero

2.1. Props des composants2/2

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