nextora-gutenberg-blocks

Bloques de Nextora

Posee el contrato de código para un bloque: metadatos, registro, interfaz de edición, renderizado dinámico, script de vista y consumo de la salida de construcción. Las reglas de apariencia son propiedad de nextora-design-system; las plantillas y patrones de nextora-site-composition; y el scaffolding de temas hijos de nextora-child-themes. Carga el skill de design-system cada vez que una solicitud toque el aspecto visual de un bloque, y carga ambos siempre que un bloque deba seguir preajustes o el conmutador de visitante.

Carga primero estas referencias

Lee solo lo que la tarea necesita, por ruta relativa desde este archivo:

Archivo	Léelo para
references/block-contract.md	Estructura de carpetas, claves de block.json, comportamiento del registrador, coerción de categorías, el generador, el shim de esbuild/window.wp y su lista de 14 dependencias, semántica de save, contratos de render y vista.
references/editor-and-repeaters.md	Los dos editores de listas reales (team-section y el repeater.tsx hijo), su semántica exacta de commit/cancel, ayudantes de rich text y media.
../nextora-ecosystem/references/source-map.md	De dónde proviene cada regla y cómo volver a verificarla; vocabulario de resolución raíz.
../nextora-ecosystem/references/quality-gates.md	Puertas de datos, paridad, activos, seguridad, i18n, accesibilidad y las recetas de aceptación compartidas aguas abajo (§8).

Nunca trates un valor citado en una referencia como actual: vuelve a leer los archivos del tema objetivo antes de editar.

Flujo de trabajo ordenado

1. Resuelve el objetivo y el tema anfitrión del bloque

Identifica la raíz del tema padre y la raíz del tema activo (hijo) desde la instalación en vivo o el repositorio proporcionado — get_template_directory() y get_stylesheet_directory(), o los encabezados de style.css. Un bloque hijo solo existe si el hijo lo registra; el registrador padre lee solo el directorio de plantillas. Nunca afirmes compatibilidad con Nextora sin la fuente real de Nextora.

2. Lee la evidencia del objetivo

En este orden, prefiriendo valores en vivo sobre cualquier cosa escrita aquí:

1. blocks/blocks.php — el registrador, su glob, si verifica legibilidad, filtros de categoría y qué archivos PHP por bloque incluye.
2. blocks/*/block.json — nombres existentes, categorías, supports, punteros de activos.
3. edit.tsx, render.php, view.ts opcional, save.tsx, register-styles.php/register-editor.php del bloque existente más cercano.
4. scripts/build-blocks.mjs — los globs de entrada exactos y el shim.
5. package.json + .nvmrc — los comandos y la versión de Node que realmente existen.
6. theme.json — los slugs de paleta, fuente, gradiente, tamaño de fuente y espaciado a los que el bloque debería referenciar.

3. Decide la reutilización antes de la creación

Extiende un bloque existente cuando la estructura de edición solicitada ya exista (otro campo de encabezado, otra lista, otro interruptor). Crea un bloque solo cuando el comportamiento o la estructura de edición solicitados no puedan expresarse mediante un bloque existente, un bloque central, un patrón o una variación de estilo de bloque. Indica qué bloque existente reutilizaste, o por qué nada encajó — y dilo en el entregable, no solo en la conversación: un docblock en la entrada del editor del bloque más una línea en el README del tema (nombrando los candidatos más cercanos que rechazaste y qué le falta a cada uno). Un transcriptor que solo lea el repositorio debe poder encontrar esa decisión.

4. Escribe primero los metadatos

block.json con apiVersion: 3, namespace/textdomain/category (nextora + nextora en el padre; <child-slug> en un hijo), atributos tipados con valores predeterminados reales, supports para la apariencia del contenedor y punteros de activos que nombren archivos construidos: editorScript: "file:./index.js", render: "file:./render.php", viewScript: "file:./view.js". La categoría en los metadatos es cosmética — tanto PHP como el editor fuerzan la categoría del namespace — así que nunca confíes en theme u otro slug para colocar el bloque.

5. Decide save, luego construye el editor

• Dinámico (PHP renderiza desde atributos): render + save: () => null.
• Persiste bloques anidados: save debe devolver useBlockProps.save() envolviendo <InnerBlocks.Content />.
• Estático: guarda exactamente lo que el parser espera.

Luego escribe edit.tsx con campos nativos — RichText para texto visible, InnerBlocks para contenido anidado, APIs de medios para archivos adjuntos, controles de enlace centrales para URLs — y InspectorControls/PanelBody para configuraciones, reutilizando el vocabulario de paneles existente. Los datos repetidos siguen references/editor-and-repeaters.md. Sin estado de UI persistido.

6. Escribe render.php (bloques dinámicos)

get_block_wrapper_attributes() en la raíz; tus propios data-*/style fusionados en su matriz de argumentos; escapado por contexto (esc_html, esc_attr, esc_url, wp_kses_post); colores con ámbito resueltos a través del ayudante del tema; cada cadena traducida en el dominio del tema objetivo. Mantén los nombres de clase de render.php alineados con la hoja de estilos del bloque.

7. Conecta comportamiento y estilos

Agrega view.ts solo si el bloque necesita comportamiento en el front-end: inicialización idempotente protegida por atributos de estado, un intercambio de carga → listo, espacio de diseño reservado, rutas de movimiento reducido y sin JS. El CSS del front-end se crea en style.css del bloque (o la importación CSS del script de vista) y se referencia a través de style/editorStyle; el CSS del inspector y la vista previa del lienzo permanece con ámbito en el bloque, nunca en wp-admin.

8. Construye, luego verifica en las superficies reales

Ejecuta el script propio del objetivo desde la raíz del tema (npm run build:blocks, o npm run build, o el npm run build:blocks del hijo). Nunca edites a mano index.js, index.asset.php, view.js o view.css. Luego aplica ../nextora-ecosystem/references/quality-gates.md y su receta de bloque §8 más los pasos específicos del bloque en references/block-contract.md §11.

Límites estrictos

• Sin segundo runtime de React, sin pipeline genérico de @wordpress/scripts, sin segundo empaquetador. Reutiliza la configuración de esbuild del tema.
• Agregar una importación no listada de @wordpress/* se construye pero puede leer un global window.wp.* indefinido: el manifiesto de activos solo enumera un conjunto fijo de 14 paquetes. Verifica el global y su handle antes de importar, o evita la importación.
• No agregues una librería que el bloque no use; las librerías ya en package.json son rangos, así que lee el lockfile antes de confiar en una API.
• No cambies la forma de un atributo persistido sin una entrada deprecated o una migración única, y nunca conviertas un esquema de lista indexada por clave a uno indexado por ID (o viceversa) para hacer conveniente un ayudante de editor.
• No agregues rutas REST, caché, telemetría, páginas de administración o abstracciones no relacionadas para satisfacer una solicitud de bloque.
• No modifiques los temas fuente mientras entregas skills o documentación.

Verificaciones de finalización

• Tema objetivo y anfitrión del bloque identificados desde sus propios archivos; nada afirmado se basa en código no leído.
• Decisión de reutilización indicada, o una razón concreta por la que el bloque tuvo que ser nuevo.
• block.json nombra un par real de namespace/categoría/textdomain y apunta solo a activos construidos; el bloque aparece bajo la categoría del namespace en el insertador.
• save coincide con el tipo de almacenamiento del bloque, verificado con un ciclo de guardar → recargar → volver a guardar sin advertencia de validación de bloque.
• El texto visible, el contenido anidado, los medios y las URLs utilizan controles de edición nativos; el editor de elementos es un único diálogo; no se persiste estado de UI.
• render.php escapa por contexto y traduce en el dominio objetivo; los colores con ámbito se resuelven a través del ayudante del tema y los valores vacíos siguen los valores predeterminados del tema.
• El comportamiento de vista es idempotente, reserva diseño y respeta movimiento reducido y sin JS.
• La salida de construcción se regeneró con el script propio del objetivo; los archivos generados no se tocan a mano.
• Se ejecutaron los pasos de aceptación relevantes de §8, o se informa claramente la superficie no verificada.

Límites

Solo instrucciones en Markdown y referencias respaldadas por el código fuente. Este skill no envía scripts en tiempo de ejecución, generadores, árboles de temas copiados, gestión de paquetes o automatización de instalación, y no modifica los temas padre o hijo.