Contratos de tipos de bloque

Este documento empezó como el inventario de la Fase 1 de los tipos de bloque core publicados que se distribuyen actualmente en WebBlocks CMS, ahora documenta también la vista de contrato de solo lectura del administrador de la Fase 2 y registra las correcciones de estandarización de carencias de la Fase 3 completadas hasta ahora, incluida la limpieza de Layout + Card para section, container, grid, cluster, card y content_header, la limpieza de Marketing / Contenido estructurado para hero, columns, column_item, cta, feature-grid y feature-item, y la limpieza de Legacy / Transitional que mantiene los slugs de compatibilidad antiguos documentados con honestidad sin promoverlos al catálogo core publicado.

La Fase 1 es únicamente documentación de solo lectura.

• No rediseña los formularios de bloque.
• No añade un constructor de formularios basado en base de datos.
• No migra el contenido de los bloques.
• No cambia el renderizado público.
• No cambia el funcionamiento actual de la edición en Admin -> System -> Block Types.

La pantalla de administración Block Types actual sigue siendo una pantalla de catálogo y metadatos. En la Fase 2 ya puede abrir un modal Contract de solo lectura para cada fila listada, pero sigue sin ser un constructor de formularios dinámico ni un editor de esquemas.

La Fase 3 de plugins añade hooks de bloque de plugin solo declarativos mediante PluginBlockTypeDefinition, PluginBlockPackDefinition y PluginBlockRegistry. Los plugins habilitados pueden exponer handles propios del plugin, como analytics-tools::score-card, para su descubrimiento, pero estas declaraciones no sustituyen a los contratos de bloque core distribuidos, las vistas de bloque core, los seeders core ni los servicios de edición de bloques. Los handles sin cualificar de estilo core, como hero, siguen perteneciendo al core y se rechazan en las declaraciones de plugins.

Un contrato de tipo de bloque es el acuerdo técnico actual sobre cómo se comporta un tipo de bloque a través de las capas del CMS:

• identidad de catálogo: slug, etiqueta, categoría, estado y metadatos de sistema o de contenedor
• origen del formulario de administración: qué parcial Blade edita actualmente el bloque y qué campos expone
• validación y gestión de peticiones: cómo normaliza y valida actualmente App\Http\Requests\Admin\BlockRequest las cargas útiles de los bloques
• propiedad del almacenamiento: qué valores residen en blocks, en filas de traducción dedicadas, en block_media o en registros relacionados
• propiedad de la traducción: qué campos dirigidos al usuario pertenecen al idioma
• propiedad compartida: qué ajustes o relaciones permanecen compartidos entre idiomas
• propiedad de medios o relaciones: media_id directo, block_media ordenado, búsquedas de navegación o relaciones dentro de la misma página
• soporte de hijos: si el bloque es un contenedor y si los tipos hijos están restringidos
• origen del renderizador público: qué parcial Blade público renderiza hoy el bloque
• contrato de raíz del renderizador: si el bloque posee su propio marcado raíz público o depende de la ruta genérica del envoltorio
• portabilidad y revisiones: si la forma de almacenamiento actual debería seguir viajando a través de revisiones, clonación, exportación/importación y promoción
• pruebas y carencias: cobertura focalizada conocida, comportamiento poco claro o deuda de compatibilidad

Términos de estado utilizados a continuación:

• clear: el formulario de administración, la gestión de peticiones, el almacenamiento y el renderizador coinciden en gran medida
• mostly clear: el contrato actual se entiende, pero tiene una salvedad destacable
• transitional: el contrato actual mantiene de forma intencionada una ruta de compatibilidad o un patrón de propiedad mixto
• needs review: las rutas de código actuales no concuerdan o el comportamiento está lo bastante poco documentado como para que la Fase 2 deba exponerlo con mayor claridad
• legacy/fallback: el comportamiento publicado depende de una ruta alternativa o de compatibilidad

El trabajo actual y futuro sobre los contratos debería mantener explícitas estas reglas de propiedad:

• el texto dirigido al usuario pertenece a las filas de traducción cuando el bloque pertenece a un idioma
• los datos operativos o de configuración compartidos pertenecen a los ajustes compartidos del bloque o a relaciones explícitas
• los medios deberían usar las rutas de propiedad media_id o block_media cuando corresponda
• evite mover contenido dirigido al usuario a un JSON de ajustes arbitrario
• mantenga documentadas las rutas de almacenamiento de compatibilidad mientras sigan afectando a la salida pública o a las importaciones

Este inventario de la Fase 1 se basa en el código fuente distribuido, no en suposiciones.

• origen del catálogo: app/Support/Blocks/CoreBlockTypeCatalogSyncer.php
• normalización de la petición de edición de bloques: app/Http/Requests/Admin/BlockRequest.php
• ayudantes de persistencia: app/Support/Blocks/BlockPayloadWriter.php, app/Support/Blocks/BlockTranslationWriter.php, app/Support/Blocks/BlockTranslationResolver.php
• registro de traducciones: app/Support/Blocks/BlockTranslationRegistry.php
• formularios de administración: resources/views/admin/blocks/types/*.blade.php
• renderizadores públicos: resources/views/pages/partials/blocks/*.blade.php
• referencias de cobertura: pruebas de catálogo de bloques, renderizado, traducción y específicas de slug en tests/Feature/

Tipos de bloque core publicados documentados actualmente aquí: 42.

La Fase 1 añade un comando de auditoría seguro para desarrolladores:

El comando es de solo lectura.

• no modifica la base de datos
• no depende del contenido del sitio instalado
• lee las definiciones del catálogo core distribuido
• verifica la presencia de los archivos del formulario de administración y del renderizador público distribuidos
• informa de los metadatos de la familia de traducción y del soporte básico de contenedores

El comando es una ayuda de actualidad para detectar desviaciones del catálogo y de la presencia de archivos. No sustituye a las notas de contrato más completas de este documento.

La Fase 2 expone los detalles del contrato en modo solo lectura en Admin -> System -> Block Types.

• cada fila puede abrir un modal Block Type Contract
• el modal es solo informativo y no envía actualizaciones
• muestra los detalles de catálogo, formulario de administración, almacenamiento, traducción, medios o relaciones, hijos, renderizador y carencias a partir del código distribuido
• no convierte la administración de Block Types en un editor de esquemas ni en un constructor de formularios
• los tipos de bloque personalizados o en borrador también pueden abrir el modal, pero pueden mostrar No shipped contract is documented for this block type yet. cuando no hay ningún contrato core definido

Actualmente, los tipos de bloque publicados no tienen cada uno su propia clase de request dedicada.

• App\Http\Requests\Admin\BlockRequest es la ruta de solicitud de edición compartida
• las ramas específicas de cada slug dentro de esa solicitud normalizan los campos hacia el almacenamiento canónico actual
• App\Support\Blocks\BlockPayloadWriter persiste el payload normalizado del bloque
• App\Support\Blocks\BlockTranslationWriter traslada los campos propiedad del idioma (locale) a filas de traducción para las familias registradas
• App\Support\Blocks\BlockTranslationResolver resuelve los valores traducidos o de reserva sobre una instancia de bloque renderizable

Esa ruta de solicitud compartida es una de las razones por las que la Fase 1 documenta primero los contratos, antes de cualquier trabajo de edición basado en esquemas.

Carencias relevantes que siguen pendientes tras las correcciones actuales de la Fase 3:

• gallery todavía conserva una ruta heredada de elementos de reserva basada en la configuración cuando las filas canónicas ordenadas de block_media no están presentes
• table — su renderizador todavía admite una ruta de reserva heredada basada en settings.rows aunque el formulario de administración principal escribe el texto traducido de las filas
• hero todavía conserva reservas de campos heredadas cuando los campos de introducción traducidos canónicos están vacíos
• feature-grid y feature-item ya están publicados porque están respaldados por el código fuente, pero siguen siendo, de forma intencionada, contratos delegados transitorios sobre las rutas de presentación compartidas de Columns o Column Item
• tabs, slider, menu y faq-list siguen existiendo como filas heredadas del catálogo en estado borrador, con formularios o renderizadores de compatibilidad, pero no son contratos publicados del núcleo y deben seguir fallando de forma segura en el modal de contrato y en la salida de auditoría
• showcase-list y contact-info solo existen como rutas de compatibilidad de renderizado público, y no como bloques publicados del catálogo del núcleo; sus enlaces basados en la configuración siguen ahora las mismas reglas de URL pública segura que el resto de renderizadores de bloques
• los catálogos publicados y en borrador coexisten, por lo que cualquier exposición futura en la administración debe distinguir explícitamente entre contratos publicados del núcleo y filas en borrador o específicas de la instalación

Trabajo de estandarización recomendado más adelante para los grupos de bloques:

• definir grupos de bloques estables propiedad del producto, como layout, contenido, navegación, patrón y avanzado, en una única fuente de verdad
• alinear las agrupaciones del selector, las de la documentación y las de la administración de Block Types con esa misma fuente
• decidir qué bloques actualmente en borrador o transitorios deben pasar a estar soportados, archivados o marcados explícitamente como heredados
• estandarizar qué contratos están respaldados por traducciones y cuáles son intencionadamente solo compartidos antes de iniciar cualquier trabajo de formularios basado en esquemas

La Fase 1 establece el inventario actual de contratos publicados sin cambiar el comportamiento de edición de bloques, su almacenamiento ni el renderizado público.

Ese era el punto de parada previsto para la versión de la Fase 1.

La Fase 2 hace visible el contrato documentado en la administración de Block Types como información de solo lectura, manteniendo sin cambios el comportamiento de edición de bloques, el almacenamiento, los renderizadores y el selector.

La Fase 3 empieza a resolver las carencias documentadas de bajo riesgo en los contratos sin añadir un editor de esquemas, un constructor dinámico de formularios ni un sistema de formularios de bloque basado en base de datos.

• code ahora sigue la ruta de traducción de texto existente para el título, la etiqueta y el cuerpo del fragmento, manteniendo compartido el lenguaje de sintaxis
• table ahora sigue la ruta de traducción de texto existente para el título y el texto de las filas, manteniendo compartido el estilo de la tabla
• breadcrumb ahora conserva al guardar la configuración compartida expuesta
• stat-card ahora utiliza la URL opcional existente en el renderizador público mediante un enlace seguro y sencillo
• link-list ahora renderiza el texto de introducción traducido existente encima de la lista de elementos hijos
• sticky-navbar ahora alinea la propiedad persistida de la raíz del Navbar con Block::ownsPublicRoot() para que el shell público no añada un contenedor genérico adicional
• image ahora sigue la ruta de traducción de imágenes existente para el pie de foto y el texto alternativo, manteniendo compartidos el medio seleccionado y la URL de enlace opcional
• gallery ahora utiliza la tabla propiedad del idioma (locale) block_gallery_item_translations para el texto alternativo, el pie de foto, el título de superposición y el texto de superposición de cada elemento, manteniendo compartidos los medios ordenados de la galería y la configuración de presentación, conservando los elementos de reserva heredados para el contenido antiguo y excluyendo el título y la descripción heredados de la galería de la edición normal y de la salida pública
• download ahora sigue la ruta de traducción de texto existente para la etiqueta visible y el texto de ayuda, manteniendo compartidos el medio seleccionado y la variante del botón
• file, video y audio ahora tienen formularios de administración de primer nivel y normalización de solicitudes, de modo que el texto visible traducido y los medios compartidos o las fuentes de URL viajan de ida y vuelta por el mismo contrato con el que ya se renderizan públicamente
• image, gallery, download, file, video y audio ya no aceptan la colocación arbitraria de nuevos hijos ni renderizan públicamente árboles de hijos históricos arbitrarios, aunque las filas hijas existentes se conservan en los árboles de bloques de la administración
• code, table, quote, toc y html ya no aceptan la colocación normal de nuevos hijos ni renderizan públicamente árboles de hijos históricos arbitrarios, aunque las filas hijas existentes se conservan en los árboles de bloques de la administración
• navbar-brand y sidebar-brand ahora comparten un contrato conservador de reserva basado en la URL guardada o en la página de inicio del sitio, y ambos conservan un nombre accesible y seguro para la salida con solo logotipo, sin forzar texto visible
• sidebar-nav-group ahora reutiliza la misma semántica de salida de elementos manuales de la barra lateral que sidebar-nav-item para los enlaces hijos anidados, conservando el contrato existente del contenedor nav-group de WebBlocks UI
• section, container, grid, cluster, card y content_header ahora usan la misma fuente de contrato distribuida en el registro, el modal de contrato de solo lectura de la administración, la salida de auditoría, la documentación y la cobertura de regresión específica
• hero, columns, column_item, cta, feature-grid y feature-item ya están publicados en el catálogo del núcleo distribuido, documentados en el registro de contratos compartido y cubiertos como contratos de marketing o de contenido estructurado respaldados por el código fuente, en lugar de permanecer solo como borradores o poco documentados
• las ediciones exclusivas de un idioma (locale) para los botones CTA gestionados y los elementos hijos estructurados ahora conservan las URL compartidas y siguen actualizando las etiquetas o el texto traducidos
• las primitivas de layout mantienen la configuración de layout compartida y la estructura de hijos en el almacenamiento canónico de bloques, en lugar de en filas de traducción o campos de texto arbitrarios
• card ahora utiliza un contrato de shell componible: la Card padre es propietaria de la raíz wb-card, las regiones de Card son propietarias de wb-card-header, wb-card-body y wb-card-footer, los bloques de región solo son válidos dentro de Card y el texto de Card guardado heredado solo se conserva mediante una ruta mínima de renderizado de reserva sin regiones
• content_header mantiene el título, la introducción y el texto meta traducidos, renderiza siempre su título como H1, ignora de forma segura los valores heredados de nivel de encabezado guardados y mantiene su raíz semántica <header class="wb-content-header"> bajo la propiedad del renderizador, sin contenedor genérico
• testimonial y stats siguen documentados con honestidad como un comportamiento de solo alias que delega en las rutas de renderizado existentes de Quote o Columns, y no como contratos publicados del núcleo independientes
• tabs, slider, menu y faq-list siguen siendo slugs en borrador o de compatibilidad de la época de los alias, y no contratos publicados del núcleo, mientras que showcase-list y contact-info siguen siendo renderizadores de compatibilidad exclusivamente públicos, sin entrada de contrato en el catálogo del núcleo distribuido