> ## Documentation Index
> Fetch the complete documentation index at: https://docs-loja.usecorvex.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Section Contract

> Contrato de uma Section — arquivos, schema, props e registro no tema.

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

1. O ID da pasta (`hero`, `faq`, …) precisa estar em `theme.json` → `sections[]`.
2. `section.jsx` exporta o componente como **default export**.
3. 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](https://docs-loja.usecorvex.com.br/reference/contracts/schema.md). Dados: [Data Contract](https://docs-loja.usecorvex.com.br/reference/contracts/data.md).

***

## 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:

```jsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
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`:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "title",
  "type": "text",
  "label": "Título",
  "default": "Bem-vindo"
}
```

No componente, use fallbacks seguros para o primeiro render:

```jsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```jsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](https://docs-loja.usecorvex.com.br/reference/runtime-api.md#edição-inline-—-duplo-clique-no-canvas).

***

## Sections com blocks

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

1. Crie `sections/{id}/blocks.json`:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "blocks": [{ "type": "heading" }, { "type": "text" }],
  "max_blocks": 12
}
```

2. Na página, cada instância da section guarda `blocks` e `block_order` — ver [Block Contract](https://docs-loja.usecorvex.com.br/reference/contracts/block.md).

3. 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](https://docs-loja.usecorvex.com.br/reference/runtime-api.md#blocks-—-adicionar,-remover-e-reordenar).

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](https://docs-loja.usecorvex.com.br/guides/theme-defaults.md).

***

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

### Fazer

```jsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

```jsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](https://docs-loja.usecorvex.com.br/guides/theme-defaults.md) |
| "+ 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](#identidade-type-estável-name-livre) |

***

## `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](https://docs-loja.usecorvex.com.br/guides/system-page-templates.md).

***

## 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 — use `enabledOn`.
* Usar tipos de campo que não estão na lista estável ([Schema overview](https://docs-loja.usecorvex.com.br/schema/overview.md)).
* Assumir que o lojista já preencheu um campo — sempre trate valores vazios.

***

## Exemplo mínimo válido

`sections/hello/schema.json`:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "type": "hello",
  "name": "Hello",
  "category": "Conteúdo",
  "settings": [
    { "id": "title", "type": "text", "label": "Título", "default": "Olá" }
  ]
}
```

`sections/hello/section.jsx`:

```jsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
export default function HelloSection({ settings = {} }) {
  return <section><p>{settings.title}</p></section>;
}
```

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

***

## Veja também

* [Block Contract](https://docs-loja.usecorvex.com.br/reference/contracts/block.md)
* [Snippet Contract](https://docs-loja.usecorvex.com.br/reference/contracts/snippet.md)
* [Preview Contract](https://docs-loja.usecorvex.com.br/reference/contracts/preview.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.