blocos-nextora-gutenberg

Blocos Nextora

Possui o contrato de código de um bloco: metadados, registro, interface do editor, renderização dinâmica, script de visualização, consumo da saída de build. As regras de aparência pertencem a nextora-design-system; templates e padrões a nextora-site-composition; scaffolding de tema filho a nextora-child-themes. Carregue a skill de design-system sempre que uma solicitação envolver a aparência de um bloco, e carregue ambas sempre que um bloco precisar seguir predefinições ou o alternador de visitantes.

Carregue estas referências primeiro

Leia apenas o que a tarefa precisa, pelo caminho relativo a partir deste arquivo:

Arquivo	Leia para
references/block-contract.md	Estrutura de pastas, chaves de block.json, comportamento do registrador, coerção de categoria, o gerador, o shim esbuild/window.wp e sua lista de dependências de 14 handles, semântica de save, contratos de render e view.
references/editor-and-repeaters.md	Os dois editores de lista reais (team-section e o filho repeater.tsx), sua semântica exata de commit/cancelar, helpers de rich text e mídia.
../nextora-ecosystem/references/source-map.md	De onde vem cada regra e como verificá-la novamente; vocabulário de resolução de raiz.
../nextora-ecosystem/references/quality-gates.md	Gates de dados, paridade, ativos, segurança, i18n, acessibilidade e as receitas de aceitação downstream compartilhadas (§8).

Nunca trate um valor citado em uma referência como atual: releia os arquivos do próprio tema alvo antes de editar.

Fluxo de trabalho ordenado

1. Resolva o alvo e o tema hospedeiro do bloco

Identifique a raiz do tema pai e a raiz do tema (filho) ativo a partir da instalação ativa ou do repositório fornecido — get_template_directory() e get_stylesheet_directory(), ou os cabeçalhos style.css. Um bloco filho só existe se o filho o registra; o registrador pai lê apenas o diretório de template. Nunca afirme compatibilidade com Nextora sem o código fonte real do Nextora.

2. Leia as evidências do próprio alvo

Nesta ordem, preferindo valores atuais a qualquer coisa escrita aqui:

1. blocks/blocks.php — o registrador, seu glob, se verifica legibilidade, filtros de categoria e quais arquivos PHP por bloco ele puxa.
2. blocks/*/block.json — nomes existentes, categorias, supports, ponteiros de ativos.
3. O edit.tsx, render.php, view.ts opcional, save.tsx, register-styles.php/register-editor.php do bloco existente mais próximo.
4. scripts/build-blocks.mjs — os globs de entrada exatos e o shim.
5. package.json + .nvmrc — os comandos e a versão do Node que realmente existem.
6. theme.json — slugs de paleta, fonte, gradiente, tamanho de fonte e espaçamento que o bloco deve referenciar.

3. Decida reutilização antes da criação

Estenda um bloco existente quando a estrutura de edição solicitada já existir (outro campo de título, outra lista, outra alternância). Crie um bloco apenas quando o comportamento ou estrutura de edição solicitado não puder ser expresso por um bloco existente, bloco principal, padrão ou variação de estilo de bloco. Indique qual bloco existente você reutilizou, ou por que nada se encaixou — e indique isso na entrega, não apenas na conversa: um docblock na entrada do editor do bloco mais uma linha no README do tema (nomeando os candidatos mais próximos que você rejeitou e o que falta em cada um). Um gravador que lê apenas o repositório deve ser capaz de encontrar essa decisão.

4. Escreva os metadados primeiro

block.json com apiVersion: 3, namespace/textdomain/categoria (nextora + nextora no pai; <slug-do-filho> em um filho), atributos tipados com valores padrão reais, supports para aparência do wrapper e ponteiros de ativos que nomeiam arquivos construídos: editorScript: "file:./index.js", render: "file:./render.php", viewScript: "file:./view.js". A categoria nos metadados é cosmética — PHP e o editor forçam a categoria do namespace — então nunca confie em theme ou outro slug para posicionar o bloco.

5. Decida save, depois construa o editor

• Dinâmico (PHP renderiza a partir de atributos): render + save: () => null.
• Persiste blocos aninhados: save deve retornar useBlockProps.save() envolvendo <InnerBlocks.Content />.
• Estático: salve exatamente o que o analisador espera.

Depois escreva edit.tsx com campos nativos — RichText para texto visível, InnerBlocks para conteúdo aninhado, APIs de mídia para anexos, controles de link principais para URLs — e InspectorControls/PanelBody para configurações, reutilizando o vocabulário de painel existente. Dados repetidos seguem references/editor-and-repeaters.md. Nenhum estado de UI persistido.

6. Escreva render.php (blocos dinâmicos)

get_block_wrapper_attributes() na raiz; seus próprios data-*/estilo mesclados em seu array de argumentos; escape por contexto (esc_html, esc_attr, esc_url, wp_kses_post); cores com escopo resolvidas através do helper do tema; toda string traduzida no domínio do tema alvo. Mantenha os nomes de classe de render.php alinhados com a folha de estilo do bloco.

7. Conecte comportamento e estilos

Adicione view.ts apenas se o bloco precisar de comportamento no front-end: inicialização idempotente protegida por atributos de estado, uma troca de carregamento → pronto, espaço de layout reservado, caminhos de movimento reduzido e sem JS. CSS de front-end é criado no style.css do bloco (ou na importação CSS do script de view) e referenciado através de style/editorStyle; CSS de inspeção e preview do canvas permanece com escopo no bloco, nunca no chrome do wp-admin.

8. Construa, depois verifique nas superfícies reais

Execute o script do próprio alvo a partir da raiz do tema (npm run build:blocks, ou npm run build, ou npm run build:blocks do filho). Nunca edite manualmente index.js, index.asset.php, view.js ou view.css. Depois aplique ../nextora-ecosystem/references/quality-gates.md e sua receita de bloco §8, além das etapas específicas do bloco em references/block-contract.md §11.

Limites rígidos

• Sem segundo runtime React, sem pipeline @wordpress/scripts genérico, sem segundo bundler. Reutilize a configuração esbuild do tema.
• Adicionar uma importação @wordpress/* não listada compila, mas pode ler um global window.wp.* indefinido: o manifesto de ativos lista apenas um conjunto fixo de 14 handles de pacotes. Verifique o global e seu handle antes de importar, ou evite a importação.
• Não adicione uma biblioteca que o bloco não usa; bibliotecas já em package.json são intervalos, então leia o lockfile antes de confiar em uma API.
• Não altere uma forma de atributo persistido sem uma entrada deprecated ou uma migração única, e nunca converta um esquema de lista indexada por chave para um esquema indexado por ID (ou vice-versa) para tornar um helper de editor conveniente.
• Não adicione rotas REST, cache, telemetria, páginas de administração ou abstrações não relacionadas para satisfazer uma solicitação de bloco.
• Não modifique os temas fonte ao entregar skills ou documentação.

Verificações de conclusão

• Tema alvo e hospedeiro do bloco identificados a partir de seus próprios arquivos; nada reivindicado se baseia em código fonte não lido.
• Decisão de reutilização declarada, ou uma razão concreta pela qual o bloco teve que ser novo.
• block.json nomeia um par real de namespace/categoria/textdomain e aponta apenas para ativos construídos; o bloco aparece sob a categoria do namespace no inserter.
• save corresponde ao tipo de armazenamento do bloco, verificado por salvar → recarregar → salvar novamente sem aviso de validação de bloco.
• Texto visível, conteúdo aninhado, mídia e URLs usam controles de edição nativos; o editor de item é um único diálogo; nenhum estado de UI é persistido.
• render.php escapa por contexto e traduz no domínio alvo; cores com escopo resolvidas através do helper do tema e valores vazios seguem os padrões do tema.
• Comportamento de visualização é idempotente, reserva layout e respeita movimento reduzido e sem JS.
• Saída de build regenerada com o script do próprio alvo; arquivos gerados não tocados manualmente.
• Etapas de aceitação relevantes da §8 executadas, ou a superfície não verificada relatada claramente.

Limites

Apenas instruções Markdown e referências baseadas em código fonte. Esta skill não fornece scripts de runtime, geradores, árvores de tema copiadas, gerenciamento de pacotes ou automação de instalação, e não modifica os códigos fonte do tema pai ou filho.