Block Contract

Um block é um subcomponente editável dentro de uma section — por exemplo um título, parágrafo ou item de FAQ.

Arquivos do block

Para cada ID em theme.json → blocks:

Arquivo	Obrigatório?
`blocks/{id}/block.jsx`	Sim
`blocks/{id}/schema.json`	Sim
`blocks/{id}/blocks.json`	Só no bloco contêiner

Registro no tema

O ID precisa estar em theme.json → blocks[].
block.jsx exporta o componente como default export.
Convém nomear {PascalCase}Block — ex.: heading → HeadingBlock.

`schema.json`

Campo	Obrigatório?
`type`	Convém ser igual ao ID da pasta
`name`	Sim — label no inspector e identidade do nó na página salva. Depois do primeiro `corvex sync`, não altere (sem “legado”, “v2”, tradução). O ID estável é `type` / pasta.
`settings`	Opcional — campos editáveis

Blocks não precisam de category.

Props do componente

Prop	O que é
`settings`	Valores do lojista — sempre dentro de `settings`
`isEditing`	Opcional — edição inline no preview
`onSettingsChange`	Opcional — `(patch) => void` com `isEditing`

export default function HeadingBlock({ settings = {} }) {
  const Tag = settings.level === 'h3' ? 'h3' : 'h2';
  return <Tag>{settings.text || 'Título'}</Tag>;
}

Não use props na raiz (text, level direto) — tudo fica em settings.*. Valores iniciais de campo: default em cada setting do schema.json, como nas sections. Looks iniciais da lista (vários slides na home): templates/*.json com blocks + block_order, não um array no JSX. theme-defaults.

Section que aceita blocks

Manifest (`sections/{id}/blocks.json`)

{
  "blocks": [{ "type": "heading" }, { "type": "text" }],
  "max_blocks": 12
}

blocks[].type precisa corresponder a um block registrado no tema.
max_blocks é opcional — limite de instâncias na section.
corvex build (≥ 2.3.4) anexa este arquivo no bundle. Não importe blocks.json no section.jsx e não declare propriedade estática no componente.

Instância na página

{
  "type": "hero",
  "settings": { "height": "large" },
  "blocks": {
    "b1": { "type": "heading", "settings": { "text": "Título", "level": "h2" } }
  },
  "block_order": ["b1"]
}

block_order define a ordem de renderização.
O lojista reordena blocks no painel Itens do editor (arrastar ≡). Na vitrine, itere block_order — ver Runtime API.

Bloco contêiner (grupo)

Um bloco com blocks/{id}/blocks.json aceita filhos diretos (um nível extra). O tipo vive no tema (blocks/group/ ou equivalente) — a plataforma não impõe um group no host.

// blocks/group/blocks.json
{
  "blocks": [{ "type": "text" }],
  "max_blocks": 12
}

Mesmo formato do manifest da seção. corvex build anexa blockManifest no componente do bloco.
Fase 1: o contêiner não pode listar outro contêiner. corvex validate rejeita isso.
No JSX do contêiner, {children} dentro de BlockCanvas (@corvex/runtime). Sem .map de filhos.
Isto não é grupo de layout (layoutGroups): aquele organiza seções globais.

Instância aninhada

{
  "type": "grouped-columns",
  "settings": {},
  "blocks": {
    "g1": {
      "type": "group",
      "settings": { "direction": "column" },
      "blocks": {
        "t1": { "type": "text", "settings": { "text": "Join the club" } }
      },
      "block_order": ["t1"]
    }
  },
  "block_order": ["g1"]
}

Bloco sem block_order (ou array vazio) é folha. Cookbook: Colunas agrupadas.

Edição inline no canvas (opcional)

Para campos text / textarea, use BlockInlineText de @corvex/runtime — duplo clique no builder com Inspecionar ativo:

import { BlockInlineText } from '@corvex/runtime';

export default function HeadingBlock({ settings = {} }) {
  return (
    <BlockInlineText
      fieldKey="text"
      tag="h2"
      value={settings.text || 'Título'}
    />
  );
}

fieldKey = id do field no schema.json do block. Detalhes: Runtime API — edição inline.

O que evitar

Usar o mesmo ID como section e block sem registrar ambos explicitamente.
Contêiner dentro de contêiner (mais de um nível extra) — fora da fase 1.
Tipos de campo fora da lista estável (Schema overview).
Mudar o id da pasta / type depois que há páginas. name é rótulo e pode mudar. Detalhe: Section Contract — identidade.

Exemplo mínimo válido

blocks/heading/schema.json:

{
  "type": "heading",
  "name": "Título",
  "settings": [
    { "id": "text", "type": "text", "label": "Texto", "default": "Título" },
    {
      "id": "level",
      "type": "select",
      "label": "Nível",
      "default": "h2",
      "options": [{ "value": "h2", "label": "H2" }, { "value": "h3", "label": "H3" }]
    }
  ]
}

blocks/heading/block.jsx:

export default function HeadingBlock({ settings = {} }) {
  const Tag = settings.level === 'h3' ? 'h3' : 'h2';
  return <Tag>{settings.text}</Tag>;
}

theme.json → "blocks": [ "heading", … ]

Introdução

Temas

Seções

Guias

Exemplos

Storefront Components

Schema

CLI

Dados

SDK

Contratos

Marketplace

Block Contract

Block Contract

Arquivos do block

Registro no tema

`schema.json`

Props do componente

Section que aceita blocks

Manifest (`sections/{id}/blocks.json`)

Instância na página

Bloco contêiner (grupo)

Instância aninhada

Edição inline no canvas (opcional)

O que evitar

Exemplo mínimo válido

Veja também

​Block Contract

​Arquivos do block

​Registro no tema

​schema.json

​Props do componente

​Section que aceita blocks

​Manifest (sections/{id}/blocks.json)

​Instância na página

​Bloco contêiner (grupo)

​Instância aninhada

​Edição inline no canvas (opcional)

​O que evitar

​Exemplo mínimo válido

​Veja também

Block Contract

Arquivos do block

Registro no tema

`schema.json`

Props do componente

Section que aceita blocks

Manifest (`sections/{id}/blocks.json`)

Instância na página

Bloco contêiner (grupo)

Instância aninhada

Edição inline no canvas (opcional)

O que evitar

Exemplo mínimo válido

Veja também