Développement de blocs WP

Quand l'utiliser

Utilisez cette skill pour les travaux de bloc, comme :

• créer un nouveau bloc ou mettre à jour un bloc existant
• modifier block.json (scripts/styles/supports/attributes/render/viewScriptModule)
• corriger « bloc invalide / ne s'enregistre pas / attributs ne persistent pas »
• ajouter un rendu dynamique (render.php / render_callback)
• dépréciations et migrations de blocs (versions deprecated)
• build tooling pour les blocs (@wordpress/scripts, @wordpress/create-block, wp-env)

Entrées requises

• Racine du repo et cible (plugin vs thème vs full site).
• Nom/espace de noms du bloc et son emplacement (chemin vers block.json si connu).
• Gamme de versions WordPress cible (surtout si vous utilisez des modules / viewScriptModule).

Procédure

0) Triage et localisation des blocs

1. Lancez le triage :
   • node skills/wp-project-triage/scripts/detect_wp_project.mjs
2. Listez les blocs (scan déterministe) :
   • node skills/wp-block-development/scripts/list_blocks.mjs
3. Identifiez la racine du bloc (répertoire contenant block.json) que vous modifiez.

Si ce repo est un full site (wp-content/ présent), précisez quel plugin/thème contient le bloc.

1) Créer un nouveau bloc (si nécessaire)

Si vous créez un nouveau bloc, préférez le scaffolding plutôt que la construction manuelle :

• Utilisez @wordpress/create-block pour générer une configuration moderne de bloc/plugin.
• Si vous avez besoin de l'Interactivity API dès le départ, utilisez le template interactif.

Lisez :

• references/creating-new-blocks.md

Après le scaffolding :

1. Relancez le script de liste des blocs et confirmez la racine du nouveau bloc.
2. Continuez avec les étapes restantes (choix du modèle, métadonnées, enregistrement, sérialisation).

2) Assurer apiVersion 3 (WordPress 6.9+)

WordPress 6.9 impose apiVersion: 3 dans le schéma block.json. Les blocs avec apiVersion 2 ou inférieur déclenchent des avertissements console quand SCRIPT_DEBUG est activé.

Pourquoi c'est important :

• WordPress 7.0 exécutera l'éditeur de posts dans une iframe quel que soit l'apiVersion du bloc.
• apiVersion 3 garantit que votre bloc fonctionne correctement à l'intérieur de l'éditeur iframé (isolation de style, unités viewport, media queries).

Migration : Passer de la version 2 à la version 3 se résume généralement à mettre à jour le champ apiVersion dans block.json. Cependant :

• Testez dans un environnement local avec l'éditeur iframe activé.
• Assurez-vous que tous les handles de style sont inclus dans block.json (les styles manquants de l'iframe ne s'appliqueront pas).
• Les scripts tiers attachés à une window spécifique peuvent avoir des problèmes de scope.

Lisez :

• references/block-json.md (détails sur apiVersion et le schéma)

3) Choisir le bon modèle de bloc

• Bloc statique (markup enregistré dans le contenu du post) : implémentez save() ; maintenez la stabilité de la sérialisation des attributs.
• Bloc dynamique (rendu serveur) : utilisez render dans block.json (ou render_callback en PHP) et gardez save() minimal ou null.
• Comportement interactif frontend :
  • Préférez viewScriptModule pour les scripts de view modernes basés sur des modules, où supporté.
  • Si vous travaillez principalement sur les directives data-wp-* ou les stores, utilisez aussi wp-interactivity-api.

4) Mettre à jour block.json en toute sécurité

Apportez des modifications dans le block.json du bloc, puis confirmez que l'enregistrement correspond aux métadonnées.

Pour des conseils champ par champ, lisez :

• references/block-json.md

Pièges courants :

• changer name casse la compatibilité (traitez-le comme une API stable)
• changer le markup enregistré sans ajouter deprecated cause « Bloc invalide »
• ajouter des attributs sans définir correctement la source/sérialisation cause « attribut non enregistré »

5) Enregistrer le bloc (enregistrement serveur préféré)

Préférez l'enregistrement PHP utilisant les métadonnées, surtout quand :

• vous avez besoin d'un rendu dynamique
• vous avez besoin de traductions (wp_set_script_translations)
• vous avez besoin d'un chargement conditionnel d'assets

Lisez et appliquez :

• references/registration.md

6) Implémenter les modèles edit/save/render

Suivez les bonnes pratiques pour les attributs de wrapper :

• Éditeur : useBlockProps()
• Save statique : useBlockProps.save()
• Rendu dynamique (PHP) : get_block_wrapper_attributes()

Lisez :

• references/supports-and-wrappers.md
• references/dynamic-rendering.md (si dynamique)

7) Inner Blocks (composition de blocs)

Si votre bloc est un « conteneur » imbriquant d'autres blocs, traitez Inner Blocks comme une fonctionnalité de première classe :

• Utilisez useInnerBlocksProps() pour intégrer les inner blocks avec les props de wrapper.
• Gardez les migrations en tête si vous changez le markup interne.

Lisez :

• references/inner-blocks.md

8) Attributs et sérialisation

Avant de changer les attributs :

• confirmez où la valeur d'attribut réside (délimiteur de commentaire vs HTML vs contexte)
• évitez la source d'attribut meta dépréciée

Lisez :

• references/attributes-and-serialization.md

9) Migrations et dépréciations (éviter « Bloc invalide »)

Si vous changez le markup enregistré ou les attributs :

1. Ajoutez une entrée deprecated (plus récent → plus ancien).
2. Fournissez save pour les anciennes versions et optionnellement un migrate pour normaliser les attributs.

Lisez :

• references/deprecations.md

10) Tooling et commandes de vérification

Préférez ce que le repo utilise déjà :

• @wordpress/scripts (courant) → lancez les scripts npm existants
• wp-env (courant) → utilisez pour WP local + E2E

Lisez :

• references/tooling-and-testing.md

Vérification

• Le bloc apparaît dans l'inserter et s'insère correctement.
• L'enregistrement + rechargement ne crée pas « Bloc invalide ».
• La sortie frontend correspond aux attentes (statique : markup enregistré ; dynamique : sortie serveur).
• Les assets se chargent où attendus (éditeur vs frontend).
• Lancez le lint/build/tests du repo que le triage recommande.

Modes d'échec / débogage

Si quelque chose échoue, commencez ici :

• references/debugging.md (pannes courantes + vérifications les plus rapides)
• references/attributes-and-serialization.md (attributs non enregistrés)
• references/deprecations.md (bloc invalide après changement)

Escalade

Si vous n'êtes pas sûr du comportement upstream/support de version, consultez d'abord les docs officielles :

• WordPress Developer Resources (Block Editor Handbook, Theme Handbook, Plugin Handbook)
• docs du repo Gutenberg pour les comportements à la pointe