Projet Niveau 3 — Bloc « Livre à la une » + endpoint REST

⏱️ TL;DR — Vous entrez sur votre terrain : React. Vous ajoutez à wpr-books un bloc Gutenberg dynamique « Livre à la une » (sélection d’un livre dans l’InspectorControls, rendu serveur) et un endpoint REST custom wpr/v1/books. Objectif : comprendre que Gutenberg, c’est du React, la mécanique block.json / edit / save / render_callback, et comment exposer proprement des données via l’API REST — la passerelle vers le headless du Niveau 4.

🎯 Niveau & objectifs

• Niveau : 3 (avancé). Prérequis : Niveau 2 (wpr-books opérationnel) ; Node.js 20+, npm ; bases React.
• Durée indicative : 8–12 h.
• Vous allez pratiquer : @wordpress/scripts, block.json, edit/save, blocs dynamiques (render_callback), InspectorControls, useSelect/@wordpress/data, register_rest_route, permissions REST.

📋 Cahier des charges

Contexte — La librairie veut mettre en avant un livre sur n’importe quelle page, avec un rendu soigné et toujours à jour. Et l’équipe front (vous, Niveau 4) a besoin d’une API propre pour consommer le catalogue.

Objectif — Livrer (a) un bloc éditeur en React qui laisse choisir un livre et l’affiche, et (b) un endpoint REST dédié au catalogue.

Périmètre inclus

1. Un bloc dynamique wpr/featured-book scaffoldé avec @wordpress/create-block (ou block.json manuel).
2. edit.js : un InspectorControls avec un sélecteur de livre (récupération via useSelect sur le store core).
3. Rendu dynamique : save renvoie null, le HTML est produit par un render_callback PHP (données toujours fraîches).
4. Attributs du bloc : bookId, et une option d’affichage (montrer le prix ou non).
5. Un endpoint REST GET /wp-json/wpr/v1/books : liste paginée (id, titre, genre, isbn, prix, lien), avec paramètres genre et per_page.
6. Un endpoint GET /wp-json/wpr/v1/books/<id> pour un livre unique.
7. permission_callback explicite sur chaque route (lecture publique assumée et justifiée).
8. Build de production propre (npm run build), assets enregistrés via block.json.

Périmètre exclu — Pas de front Next.js (Niveau 4), pas d’écriture via REST (lecture seule), pas de WooCommerce.

Contraintes

• Le bloc doit être dynamique (pas de HTML figé dans le contenu du post).
• L’endpoint REST n’expose que les champs voulus (pas de fuite de meta privées).
• permission_callback jamais absent (ne jamais laisser __return_true sans y avoir réfléchi).

Livrables

• Le plugin wpr-books enrichi (bloc + REST), buildé.
• Un court README : comment builder, où est l’endpoint, exemples de réponses JSON.

✅ Critères de réussite

• Le bloc « Livre à la une » s’insère et propose de choisir un livre dans le panneau latéral.
• Modifier le prix du livre en base met à jour l’affichage du bloc sans ré-éditer la page (preuve du rendu dynamique).
• GET /wp-json/wpr/v1/books?genre=roman&per_page=5 renvoie un JSON propre et paginé.
• GET /wp-json/wpr/v1/books/<id> renvoie le bon livre ou un 404 REST correct.
• Aucune meta privée ne fuit dans les réponses.
• npm run build produit des assets chargés via block.json.

🗺️ Endroits à visiter

💡 Pour un dev React — Vous êtes chez vous : edit.js est un composant React avec des hooks (useSelect, useBlockProps), InspectorControls est un portail vers la sidebar, et block.json est le manifeste du composant (comme un package.json de bloc). La seule vraie nouveauté : le bloc dynamique, où save ne rend rien et c’est PHP (render_callback) qui produit le HTML final — pour que la donnée reste fraîche côté serveur. Gardez ce modèle en tête, il explique pourquoi Gutenberg n’est pas « juste un éditeur ».

⚠️ Piège — Ne mettez jamais 'permission_callback' => '__return_true' par réflexe : c’est le trou de sécurité n°1 des endpoints custom. Même en lecture publique, écrivez-le explicitement et demandez-vous qui doit pouvoir lire quoi.

🚀 Étapes suggérées

1. npx @wordpress/create-block (ou block.json manuel) dans le plugin.
2. edit.js statique d’abord (affiche « Livre à la une »), vérifier l’insertion.
3. Ajouter InspectorControls + SelectControl alimenté par useSelect.
4. Passer le bloc en dynamique : save → null, render_callback PHP.
5. Créer le namespace REST wpr/v1 + route books (liste).
6. Ajouter la route books/<id> + permission_callback.
7. Nettoyer les champs exposés ; tester dans le navigateur.

🎁 Bonus

• Ajoutez un contrôle de couleur au bloc via supports (color, typography).
• Mettez en cache la réponse REST liste (transient) et invalidez-la sur save_post.
• Ajoutez un endpoint d’écriture protégé par capability (préparez le terrain produit).

🔗 Chapitres du cours liés

• Partie 8 — Gutenberg : blocs custom en React
• Partie 9 — REST API & WordPress headless

Projet suivant : Niveau 4 — HeadlessShelf, front Next.js.