Contrats de types de bloc

Ce document a débuté comme l'inventaire de la phase 1 des types de bloc core publiés actuellement livrés dans WebBlocks CMS ; il documente désormais aussi la vue de contrat en lecture seule de l'administration issue de la phase 2 et consigne les correctifs de standardisation des écarts de la phase 3 réalisés à ce jour, y compris le nettoyage Layout + Card pour section, container, grid, cluster, card et content_header, le nettoyage Marketing / Contenu structuré pour hero, columns, column_item, cta, feature-grid et feature-item, ainsi que le nettoyage Legacy / Transitional qui garde les anciens slugs de compatibilité documentés honnêtement sans les promouvoir dans le catalogue core publié.

La phase 1 est uniquement une documentation en lecture seule.

• Elle ne repense pas les formulaires de bloc.
• Elle n'ajoute pas de générateur de formulaires piloté par la base de données.
• Elle ne migre pas le contenu des blocs.
• Elle ne modifie pas le rendu public.
• Elle ne modifie pas le fonctionnement actuel des modifications dans Admin -> System -> Block Types.

L'écran d'administration Block Types actuel reste un écran de catalogue et de métadonnées. En phase 2, il peut désormais ouvrir une fenêtre modale Contract en lecture seule pour chaque ligne listée, mais il n'est toujours ni un générateur de formulaires dynamique ni un éditeur de schémas.

La phase 3 des plugins ajoute des hooks de bloc de plugin purement déclaratifs via PluginBlockTypeDefinition, PluginBlockPackDefinition et PluginBlockRegistry. Les plugins activés peuvent exposer des handles appartenant au plugin, tels que analytics-tools::score-card, à des fins de découverte, mais ces déclarations ne remplacent pas les contrats de bloc core livrés, les vues de bloc core, les seeders core ni les services d'édition de blocs. Les handles non qualifiés de style core, tels que hero, restent la propriété du core et sont rejetés pour les déclarations de plugins.

Un contrat de type de bloc est l'accord technique actuel décrivant le comportement d'un type de bloc à travers les différentes couches du CMS :

• identité de catalogue : slug, libellé, catégorie, statut et métadonnées de système ou de conteneur
• source du formulaire d'administration : quel partiel Blade édite actuellement le bloc et quels champs il expose
• validation et traitement des requêtes : comment App\Http\Requests\Admin\BlockRequest normalise et valide actuellement les charges utiles des blocs
• propriété du stockage : quelles valeurs résident dans blocks, dans des lignes de traduction dédiées, dans block_media ou dans des enregistrements liés
• propriété de la traduction : quels champs destinés à l'utilisateur appartiennent à la langue
• propriété partagée : quels réglages ou relations restent partagés entre les langues
• propriété des médias ou des relations : media_id direct, block_media ordonné, recherches de navigation ou relations au sein d'une même page
• prise en charge des enfants : si le bloc est un conteneur et si les types enfants sont restreints
• source du moteur de rendu public : quel partiel Blade public rend le bloc aujourd'hui
• contrat de racine du moteur de rendu : si le bloc possède son propre balisage racine public ou s'appuie sur le chemin générique du wrapper
• portabilité et révisions : si la forme de stockage actuelle doit continuer à circuler à travers les révisions, le clonage, l'export/import et la promotion
• tests et écarts : couverture ciblée connue, comportement peu clair ou dette de compatibilité

Termes de statut utilisés ci-dessous :

• clear : le formulaire d'administration, le traitement des requêtes, le stockage et le moteur de rendu concordent pour l'essentiel
• mostly clear : le contrat actuel est compréhensible mais comporte une réserve notable
• transitional : le contrat actuel conserve intentionnellement un chemin de compatibilité ou un modèle de propriété mixte
• needs review : les chemins de code actuels divergent ou le comportement est suffisamment peu documenté pour que la phase 2 doive le mettre en évidence plus clairement
• legacy/fallback : le comportement publié dépend d'un chemin de repli ou de compatibilité

Les travaux actuels et futurs sur les contrats doivent garder ces règles de propriété explicites :

• le texte destiné à l'utilisateur appartient aux lignes de traduction lorsque le bloc appartient à une langue
• les données opérationnelles ou de réglage partagées appartiennent aux réglages partagés du bloc ou à des relations explicites
• les médias doivent utiliser les chemins de propriété media_id ou block_media lorsque cela s'applique
• évitez de déplacer du contenu destiné à l'utilisateur vers un JSON de réglages arbitraire
• gardez les chemins de stockage de compatibilité documentés tant qu'ils influent encore sur la sortie publique ou les imports

Cet inventaire de la phase 1 s'appuie sur le code source livré, et non sur des suppositions.

• source du catalogue : app/Support/Blocks/CoreBlockTypeCatalogSyncer.php
• normalisation de la requête d'édition de bloc : app/Http/Requests/Admin/BlockRequest.php
• utilitaires de persistance : app/Support/Blocks/BlockPayloadWriter.php, app/Support/Blocks/BlockTranslationWriter.php, app/Support/Blocks/BlockTranslationResolver.php
• registre des traductions : app/Support/Blocks/BlockTranslationRegistry.php
• formulaires d'administration : resources/views/admin/blocks/types/*.blade.php
• moteurs de rendu publics : resources/views/pages/partials/blocks/*.blade.php
• références de couverture : tests de catalogue de blocs, de rendu, de traduction et spécifiques aux slugs dans tests/Feature/

Types de bloc core publiés actuellement documentés ici : 42.

La phase 1 ajoute une commande d'audit sans risque destinée aux développeurs :

La commande est en lecture seule.

• elle ne modifie pas la base de données
• elle ne dépend pas du contenu du site installé
• elle lit les définitions du catalogue core livré
• elle vérifie la présence des fichiers de formulaire d'administration et de moteur de rendu public livrés
• elle rend compte des métadonnées de famille de traduction et de la prise en charge de base des conteneurs

La commande est une aide à l'actualisation permettant de repérer les écarts de catalogue et de présence de fichiers. Elle ne remplace pas les notes de contrat plus complètes de ce document.

La phase 2 expose les détails du contrat en lecture seule dans Admin -> System -> Block Types.

• chaque ligne peut ouvrir une fenêtre modale Block Type Contract
• la fenêtre modale est purement informative et ne soumet aucune mise à jour
• elle affiche les détails de catalogue, de formulaire d'administration, de stockage, de traduction, de médias ou de relations, d'enfants, de moteur de rendu et d'écarts à partir du code livré
• elle ne transforme pas l'administration Block Types en éditeur de schémas ou en générateur de formulaires
• les types de bloc personnalisés ou en brouillon peuvent également ouvrir la fenêtre modale, mais peuvent afficher No shipped contract is documented for this block type yet. lorsqu'aucun contrat core n'est défini

Aujourd'hui, les types de bloc publiés ne disposent pas chacun de leur propre classe request dédiée.

• App\Http\Requests\Admin\BlockRequest est le chemin de requête d'édition partagé
• les branches spécifiques à chaque slug dans cette requête normalisent les champs vers le stockage canonique actuel
• App\Support\Blocks\BlockPayloadWriter persiste la charge utile normalisée du bloc
• App\Support\Blocks\BlockTranslationWriter déplace les champs appartenant à la langue (locale) vers les lignes de traduction des familles enregistrées
• App\Support\Blocks\BlockTranslationResolver résout les valeurs traduites ou de repli sur une instance de bloc affichable

Ce chemin de requête partagé est l'une des raisons pour lesquelles la Phase 1 documente d'abord les contrats, avant tout travail d'édition piloté par schéma.

Lacunes importantes encore présentes après les correctifs actuels de la Phase 3 :

• gallery conserve encore un chemin d'éléments de repli hérité, basé sur les réglages, lorsque les lignes canoniques ordonnées de block_media sont absentes
• table — son moteur de rendu prend encore en charge un chemin de repli hérité basé sur settings.rows même si le formulaire d'administration principal écrit le texte traduit des lignes
• hero conserve encore des replis de champs hérités lorsque les champs d'introduction traduits canoniques sont vides
• feature-grid et feature-item sont désormais publiés car ils s'appuient sur le code source, mais ils restent volontairement des contrats délégués transitoires au-dessus des chemins de présentation partagés Columns ou Column Item
• tabs, slider, menu et faq-list existent encore comme lignes héritées du catalogue à l'état de brouillon, avec des formulaires ou moteurs de rendu de compatibilité, mais ce ne sont pas des contrats publiés du cœur et ils doivent continuer à échouer de façon sûre dans la fenêtre modale de contrat et dans la sortie d'audit
• showcase-list et contact-info n'existent que comme chemins de compatibilité pour le rendu public, et non comme blocs publiés du catalogue du cœur ; leurs liens issus des réglages suivent désormais les mêmes règles d'URL publique sûre que les autres moteurs de rendu de blocs
• les catalogues publiés et les catalogues en brouillon coexistent : toute exposition future dans l'administration doit donc distinguer explicitement les contrats publiés du cœur des lignes en brouillon ou spécifiques à l'installation

Travail de standardisation recommandé ultérieurement pour les groupes de blocs :

• définir des groupes de blocs stables appartenant au produit, comme layout, contenu, navigation, motif et avancé, dans une source de vérité unique
• aligner les regroupements du sélecteur, ceux de la documentation et ceux de l'administration Block Types sur cette même source
• décider quels blocs actuellement en brouillon ou transitoires doivent devenir pris en charge, archivés ou explicitement hérités
• standardiser quels contrats reposent sur des traductions et lesquels sont volontairement partagés uniquement, avant de commencer tout travail de formulaire piloté par schéma

La Phase 1 établit l'inventaire actuel des contrats publiés sans modifier le comportement d'édition des blocs, leur stockage ni le rendu public.

C'était le point d'arrêt prévu pour la livraison de la Phase 1.

La Phase 2 rend le contrat documenté visible dans l'administration Block Types sous forme d'information en lecture seule, tout en laissant inchangés le comportement d'édition des blocs, le stockage, les moteurs de rendu et le sélecteur.

La Phase 3 commence à résoudre les lacunes documentées à faible risque des contrats sans ajouter d'éditeur de schéma, de générateur de formulaires dynamique ni de système de formulaires de blocs piloté par la base de données.

• code suit désormais le chemin de traduction de texte existant pour le titre, le libellé et le corps de l'extrait, tout en gardant le langage de syntaxe partagé
• table suit désormais le chemin de traduction de texte existant pour le titre et le texte des lignes, tout en gardant le style de tableau partagé
• breadcrumb conserve désormais les réglages partagés exposés lors de l'enregistrement
• stat-card utilise désormais l'URL facultative existante dans le moteur de rendu public via un lien simple et sûr
• link-list affiche désormais le texte d'introduction traduit existant au-dessus de la liste des éléments enfants
• sticky-navbar aligne désormais la propriété persistée de la racine de la Navbar sur Block::ownsPublicRoot() afin que le shell public n'ajoute pas d'enveloppe générique supplémentaire
• image suit désormais le chemin de traduction d'images existant pour la légende et le texte alternatif, tout en gardant partagés le média sélectionné et l'URL de lien facultative
• gallery utilise désormais la table dépendante de la langue (locale) block_gallery_item_translations pour le texte alternatif, la légende, le titre de superposition et le texte de superposition de chaque élément, tout en gardant partagés les médias ordonnés de la galerie et les réglages de présentation, en conservant les éléments de repli hérités pour les anciens contenus et en excluant le titre et la description hérités de la galerie de l'édition normale et de la sortie publique
• download suit désormais le chemin de traduction de texte existant pour le libellé visible et le texte d'aide, tout en gardant partagés le média sélectionné et la variante de bouton
• file, video et audio disposent désormais de formulaires d'administration à part entière et d'une normalisation des requêtes, de sorte que le texte visible traduit et les médias partagés ou les sources d'URL font l'aller-retour par le même contrat que celui utilisé pour leur rendu public
• image, gallery, download, file, video et audio n'acceptent plus le placement arbitraire de nouveaux enfants et n'affichent plus publiquement d'arbres d'enfants historiques arbitraires, tandis que les lignes enfants existantes restent conservées dans les arbres de blocs de l'administration
• code, table, quote, toc et html n'acceptent plus le placement normal de nouveaux enfants et n'affichent plus publiquement d'arbres d'enfants historiques arbitraires, tandis que les lignes enfants existantes restent conservées dans les arbres de blocs de l'administration
• navbar-brand et sidebar-brand partagent désormais un contrat de repli prudent basé sur l'URL enregistrée ou la page d'accueil du site, et tous deux conservent un nommage accessible et sûr pour une sortie limitée au logo, sans imposer de texte visible
• sidebar-nav-group réutilise désormais la même sémantique de sortie des éléments manuels de la barre latérale que sidebar-nav-item pour les liens enfants imbriqués, tout en conservant le contrat existant de l'enveloppe nav-group de WebBlocks UI
• section, container, grid, cluster, card et content_header utilisent désormais la même source de contrat livrée dans le registre, la fenêtre modale de contrat en lecture seule de l'administration, la sortie d'audit, la documentation et la couverture de régression ciblée
• hero, columns, column_item, cta, feature-grid et feature-item sont désormais publiés dans le catalogue du cœur livré, documentés dans le registre de contrats partagé et couverts comme contrats marketing ou de contenu structuré adossés au code source, au lieu de rester à l'état de brouillon ou sous-documentés
• les modifications propres à une seule langue (locale) pour les boutons CTA gérés et les éléments enfants structurés conservent désormais les URL partagées tout en mettant à jour les libellés ou textes traduits
• les primitives de layout conservent les réglages de layout partagés et la structure des enfants dans le stockage canonique des blocs, plutôt que dans des lignes de traduction ou des champs de texte arbitraires
• card utilise désormais un contrat de shell composable : la Card parente possède la racine wb-card, les régions de Card possèdent wb-card-header, wb-card-body et wb-card-footer, les blocs de région ne sont valides que sous Card, et le texte Card enregistré hérité n'est conservé que via un chemin de rendu de repli minimal sans région
• content_header conserve le titre, l'introduction et le texte meta traduits, affiche toujours son titre en H1, ignore de manière sûre les valeurs de niveau de titre héritées enregistrées et conserve sa racine sémantique <header class="wb-content-header"> sous la responsabilité du moteur de rendu, sans enveloppe générique
• testimonial et stats restent documentés honnêtement comme un comportement de simple alias qui délègue aux chemins de rendu existants Quote ou Columns, plutôt que comme des contrats publiés du cœur autonomes
• tabs, slider, menu et faq-list restent des slugs en brouillon ou de compatibilité de l'époque des alias, et non des contrats publiés du cœur, tandis que showcase-list et contact-info restent des moteurs de rendu de compatibilité uniquement publics, sans entrée de contrat dans le catalogue du cœur livré