Section Contract

Uma section é um componente React que ocupa uma região da página. O lojista configura textos, cores e outros campos no Editor; sua section recebe esses valores e renderiza o HTML.

Arquivos da section

Para cada ID listado em theme.json → sections:

Arquivo	Obrigatório?
`sections/{id}/section.jsx`	Sim
`sections/{id}/schema.json`	Sim
`sections/{id}/styles.css`	Opcional
`sections/{id}/blocks.json`	Opcional — só se a section aceita blocks

Registro no tema

O ID da pasta (hero, faq, …) precisa estar em theme.json → sections[].
section.jsx exporta o componente como default export.
Convém nomear o componente {PascalCase}Section — ex.: pasta hero → HeroSection.

O comando corvex build inclui o componente no bundle do tema. A CLI anexa metadados no bundle — não copie isso no section.jsx:

Arquivo no tema	O que o build faz	CLI
`schema.json` da section	`Component.schema` + defaults do inspector	≥ 2.3.3
`blocks.json` da section	lista de blocks do inspector	≥ 2.3.4
`schema.json` do block	`Component.schema` do block	≥ 2.3.5

O name do inspector vem de schema.json → name. Não declare propriedade estática no componente.

Identidade: `type` estável, `name` livre

O ID da seção é a pasta. A CLI descobre o componente por esse nome. Se schema.json tiver type, use o mesmo id. Não mude a pasta depois que existem páginas. name é o rótulo da paleta e do inspector. Pode traduzir, acrescentar marca ou “(legado)”. O editor associa o nó a esse rótulo e também aceita o id da pasta e os nomes antigos do lockfile. Nós que já abrem não são reescritos. schema.identity.json guarda o name atual e os nomes já vistos (sectionAliases / blockAliases). O corvex validate não recusa rename. Commite o arquivo: o build injeta os nomes antigos no bundle para rascunhos velhos abrirem. Opcional: nameAliases no próprio schema.json se um rascunho usa um texto que o lockfile ainda não viu. Não atribua propriedade no section.jsx. Não apague o lockfile. Não mude o id da pasta / type se páginas já existem.

`schema.json`

Descreve como a section aparece no Editor e quais campos o lojista pode editar.

Campo	Obrigatório?	Descrição
`name`	Sim	Rótulo na paleta e no inspector. Pode mudar.
`category`	Sim	Grupo na paleta (ex.: Conteúdo, Banner)
`settings`	Opcional	Lista de campos editáveis
`type`	Opcional	Convém ser igual ao ID da pasta
`enabledOn`	Opcional	Limita em quais páginas a section pode ser usada
`data`	Opcional	Dados da loja que a section precisa (produtos, coleção, …)

Detalhes dos campos: Schema Contract. Dados: Data Contract.

Props do componente

Quando a Corvex renderiza sua section, ela chama seu componente React com estas props:

Prop	O que é
`settings`	Valores que o lojista configurou no Editor (sempre presente)
`data`	Dados da loja — só quando você declarou `data` no schema ou um loader
`isEditing`	`true` no preview do Editor — permite edição inline
`onSettingsChange`	Função para atualizar `settings` durante edição inline

Exemplo mínimo:

export default function HeroSection({ settings = {} }) {
  return (
    <section>
      <h1>{settings.title}</h1>
    </section>
  );
}

Leia sempre de settings — não espere title direto na raiz das props, nem uma prop config.

Valores iniciais (defaults)

Use o campo default em cada setting do schema.json:

{
  "id": "title",
  "type": "text",
  "label": "Título",
  "default": "Bem-vindo"
}

No componente, use fallbacks seguros para o primeiro render:

const title = settings.title ?? 'Bem-vindo';

Quando o lojista adiciona a section pela paleta, o Editor usa esses defaults.

Schema e dados no mesmo arquivo (opcional)

Você pode exportar metadados junto com o componente:

import { defineSection, defineSectionData } from '@corvex/theme-sdk';

export const schema = defineSection({
  name: 'Hero',
  category: 'Banner',
  settings: [{ id: 'title', type: 'text', label: 'Título', default: 'Olá' }],
});

export const data = defineSectionData(async ({ storefront, settings }) => ({
  products: await storefront.products.list({ first: settings.limit ?? 4 }),
}));

HeroSection.schema = schema;
HeroSection.data = data;

Use defineSectionData quando a busca de dados é mais complexa que as chaves simples de schema.data.

Edição inline (opcional)

Para permitir que o lojista edite texto direto no preview:

SectionChrome — envolve a section no builder
InlineText — field text/textarea da section (propKey = id do schema)
BlockInlineText — field text/textarea de um block (fieldKey = id do schema)

Duplo clique funciona no builder com Inspecionar ativo. Guia completo: Runtime API — edição inline.

Sections com blocks

Se a section contém subcomponentes editáveis (título, item de FAQ, slide, …):

Crie sections/{id}/blocks.json:

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

Na página, cada instância da section guarda blocks e block_order — ver Block Contract.
No JSX, no canvas do editor, renderize os blocos com {children} dentro de SectionBlockCanvas. Use block_order e blocks só como fallback da vitrine. Não desenhe cards manuais no editor. Veja Runtime API — blocos.

O arquivo blocks.json informa ao Editor quais tipos o lojista pode adicionar. Sem ele (e sem CLI ≥ 2.3.4), o canvas fica só com o chrome da section e {children} vazio. Slides/itens visíveis antes do lojista editar: declare-os em templates/*.json, não no JSX. theme-defaults.

Fazer / não fazer (section.jsx)

Fazer

import { SectionBlockCanvas, SectionChrome, useSectionBlockCount } from '@corvex/runtime';

export default function HeroSlideshowSection({ settings = {}, children }) {
  const count = useSectionBlockCount();

  return (
    <SectionChrome settings={settings}>
      <section>
        {count === 0 ? (
          <p>Adicione um slide ao banner.</p>
        ) : (
          <SectionBlockCanvas>{children}</SectionBlockCanvas>
        )}
      </section>
    </SectionChrome>
  );
}

Leia settings.{id} (mesmo id do schema.json).
Canvas: um SectionBlockCanvas e {children} direto — sem .map / hidden em cada child.
Contagem de slides: useSectionBlockCount().
Empty state quando a contagem é 0. Looks iniciais em templates/*.json.

Não fazer

import blocksManifest from './blocks.json';
import schema from './schema.json';

HeroSlideshowSection.displayName = 'Banner principal';
HeroSlideshowSection.schema = schema;
HeroSlideshowSection.nameAliases = ['Banner'];

Proibido no tema	Por quê
`import './blocks.json'` ou `import './schema.json'` no `section.jsx`	O build já anexa. Duplicar deixa a lista de blocks desatualizada (inspetor de slide numa promo-bar).
`displayName` ou qualquer propriedade no componente (incl. aliases de nome antigo)	O nome vem de `schema.json` → `name`. Textos antigos de rascunho: `nameAliases` no JSON. O host registra; o tema não.
Mudar a pasta / `type` depois que há páginas	Identidade estável do nó. `name` pode mudar.
Inspector montado no JSX	O inspector é o `schema.json`.
Pacote que não seja `@corvex/runtime` ou `@corvex/theme-sdk`	Só esses dois.
Banners hardcoded quando `count === 0`	Some no primeiro block do lojista e não é editável.

defineSection() no JSX continua opcional para loaders de dados. Isso não substitui o schema.json em disco.

Erros

Sintoma	Causa	O que fazer
Inspector sem lista Itens	Falta `blocks.json`, ID ausente em `theme.json` → `blocks[]`, ou CLI < 2.3.4	Crie `blocks.json`, registre o block, `corvex build` + `corvex sync` com CLI ≥ 2.3.5
”Este item não possui configurações”	Falta `blocks/{id}/schema.json` ou CLI < 2.3.5	Schema do block no disco; CLI ≥ 2.3.5
Inspetor mostra campos de outro tipo de block	Lista de blocks escrita no JSX	Apague import e propriedade estática do componente, rebuild, sync
Recarregar o editor mostra banners de fábrica; clicar no bloco mostra os do lojista	Theme Defaults no template competindo com o rascunho, ou `{children}` vazio no primeiro paint	Blocks reais em `templates`; empty state sem imagens hardcoded; theme-defaults
”+ Adicionar Slide” numa faixa de texto	`blocks.json` com `type` errado	O `type` tem que ser o ID em `blocks/`
Canvas em branco depois de renomear a pasta	A pasta ou o `type` mudou com páginas já salvas	Não mude o id da pasta. Atualize o editor se o rótulo antigo não abrir. identidade

`enabledOn`

Quando presente, a section só aparece na paleta dos templates listados. Valores aceitos pelo validador: index, product, collection, category, search, cart, page, blog, article, 404, password, maintenance. Omita enabledOn para permitir a seção em qualquer página. Array vazio é inválido. 404, password e maintenance são templates recomendados, não obrigatórios. Ver Páginas de sistema.

Chaves de `schema.data`

products, product, collection, collections, categories, cart, discount_ranges, payment_discounts, coupons, search, recommendations, reviews, reviews_summary, blog, article, page

O que evitar

Buscar produtos ou coleções sem declarar data no schema ou um loader explícito.
Usar contexts no schema — em V2 use enabledOn.
Usar tipos de campo que não estão na lista estável (Schema overview).
Assumir que o lojista já preencheu um campo — sempre trate valores vazios.

Exemplo mínimo válido

sections/hello/schema.json:

{
  "type": "hello",
  "name": "Hello",
  "category": "Conteúdo",
  "settings": [
    { "id": "title", "type": "text", "label": "Título", "default": "Olá" }
  ]
}

sections/hello/section.jsx:

export default function HelloSection({ settings = {} }) {
  return <section><p>{settings.title}</p></section>;
}

theme.json → "sections": [ "hello", … ]

Introdução

Temas

Seções

Guias

Exemplos

Storefront Components

Schema

CLI

Dados

SDK

Contratos

Marketplace

Section Contract

Section Contract

Arquivos da section

Registro no tema

Identidade: `type` estável, `name` livre

`schema.json`

Props do componente

Valores iniciais (defaults)

Schema e dados no mesmo arquivo (opcional)

Edição inline (opcional)

Sections com blocks

Fazer / não fazer (section.jsx)

Fazer

Não fazer

Erros

`enabledOn`

Chaves de `schema.data`

O que evitar

Exemplo mínimo válido

Veja também

​Section Contract

​Arquivos da section

​Registro no tema

​Identidade: type estável, name livre

​schema.json

​Props do componente

​Valores iniciais (defaults)

​Schema e dados no mesmo arquivo (opcional)

​Edição inline (opcional)

​Sections com blocks

​Fazer / não fazer (section.jsx)

​Fazer

​Não fazer

​Erros

​enabledOn

​Chaves de schema.data

​O que evitar

​Exemplo mínimo válido

​Veja também

Section Contract

Arquivos da section

Registro no tema

Identidade: `type` estável, `name` livre

`schema.json`

Props do componente

Valores iniciais (defaults)

Schema e dados no mesmo arquivo (opcional)

Edição inline (opcional)

Sections com blocks

Fazer / não fazer (section.jsx)

Fazer

Não fazer

Erros

`enabledOn`

Chaves de `schema.data`

O que evitar

Exemplo mínimo válido

Veja também