Defaults de section e block

Como o tema mostra conteúdo inicial (slides, banners, itens) e o que some quando o lojista personaliza.

Quero banners/slides na seção nova. Quando o lojista adicionar os próprios blocks, esses defaults não podem “competir” com o conteúdo real.

Há três camadas. Não misture. Não invente um quarto mecanismo no JSX.

Theme Code (JSX + schema)
Theme Defaults (templates/*.json, groups/*.json)
Merchant Content (Editor → publicar)

---

O que cada camada faz

Camada	Onde	Papel	Some quando o lojista personaliza?
Campo default no schema	schema.json da section ou do block	Valor inicial de um campo (título, intervalo, texto). Inspector usa value ?? default.	Só daquele campo, quando o lojista preenche ou limpa.
Theme Defaults	templates/*.json, groups/*.json	Instâncias reais de section e block no layout inicial da página.	Não “somem”: viram conteúdo da loja. O lojista edita, reordena ou exclui.
Fallback visual de campo vazio	block.jsx / section.jsx	Um slide já existente sem imagem: gradiente, cor, alt.	Some naquele block quando settings.image (etc.) está preenchido.
Preset	presets em schema.json da section ou block	Variante no modal Adicionar seção / Adicionar bloco (settings e, na seção, blocos iniciais).	Viram conteúdo real após adicionar; o lojista edita como qualquer seção/bloco.

Não existe “array de banners fantasma no JSX que some no primeiro block adicionado”. Isso gera blocks fantasma: não dá para selecionar, arrastar nem persistir.

Presets: section-presets. Não use preset para substituir templates/*.json na instalação.

---

Regra para LLM e tema

1. Looks da home / PDP / coleção na instalação → templates/{type}.json com blocks + block_order preenchidos. Cada item é um block de verdade (type = pasta em blocks/).
2. Looks do header/footer → groups/*.json do mesmo jeito.
3. Campo de um block novo (lojista clica “Adicionar slide”) → default no blocks/{id}/schema.json. O build copia esses defaults para o componente quando ele ainda não tem props próprias. Não declare propriedade estática no componente. Imagem: default só se for asset do tema (URL ou path estável); senão deixe vazio e use fallback visual.
4. Seção sem nenhum block (paleta “Adicionar seção”, ou lojista apagou todos) → empty state da UI (“Adicione um slide”), não 2–3 <img> hardcoded.
5. Nunca faça:

// PROIBIDO
const slides = children?.length ? children : DEFAULT_BANNERS.map(...)

// PROIBIDO
{useSectionBlockCount() === 0 && <img src="/banner-padrao.jpg" />}

Esses nós não entram na árvore do Editor. No primeiro block real, o “padrão” some de uma vez e o lojista não consegue editar o banner que via antes.

---

Slideshow / lista / cards — padrão canônico

Theme Defaults (o que o lojista vê antes de mexer):

{
  "type": "slider",
  "settings": { "autoplay": true, "interval": 5 },
  "blocks": {
    "slide-1": {
      "type": "slider-slide",
      "settings": {
        "heading": "Primeiro slide",
        "text": "Conteúdo inicial do tema."
      }
    },
    "slide-2": {
      "type": "slider-slide",
      "settings": {
        "heading": "Segundo slide",
        "text": "O lojista edita ou exclui este block."
      }
    }
  },
  "block_order": ["slide-1", "slide-2"]
}

JSX da section — só {children}:

<SectionBlockCanvas className="slider__track">
  {children}
</SectionBlockCanvas>

JSX do block — fallback do campo, não da lista:

const bg = settings.image
  ? `url(${settings.image}) center/cover`
  : 'linear-gradient(135deg, #374151, #111827)';

Quando o lojista adiciona um slide, o novo block usa default do schema. Os slides do template continuam até ele excluir. Isso é o comportamento certo: personalizar ≠ descartar o layout inicial inteiro.

Se o produto quiser “ao adicionar o primeiro slide, sumir os de fábrica”, a ação é excluir os blocks do template no Editor — não um if no tema.

---

Empty state (zero blocks)

Use useSectionBlockCount() === 0 só para mensagem / altura mínima / esconder dots do carrossel. Não invente slides.

Contagem	O que renderizar
0	Empty state (opcional no canvas). Sem banners falsos.
≥ 1	Só {children} / blocks persistidos.

---

Settings da section vs blocks

• Autoplay, altura, intervalo → default no schema da section.
• Cada banner, depoimento, item de FAQ → block no template (Theme Defaults) + default nos campos do block.
• Não coloque slides: [{ image, title }, …] num setting da section se o Editor já gerencia blocks.

---

corvex sync

corvex sync --keep-content não reescreve o draft da loja com os JSON locais. Mudar templates/index.json depois da loja já ter conteúdo não reaparece na página até o lojista resetar o template ou você sincronizar sem preservar conteúdo.

Theme Defaults valem na primeira hidratação daquele template (instalação / draft vazio).

---

Checklist

• Looks iniciais em templates/*.json (blocks + block_order), não no JSX
• Cada type de block existe em theme.json → blocks[] e no bundle
• default só em campos do schema. Sem propriedade estática no componente
• Fallback visual só quando um setting está vazio
• Zero blocks → empty state, não lista hardcoded
• Presets só no modal Adicionar; slides da home vêm de templates/*.json
• Canvas sempre {children} — Runtime API

Veja também: Templates de página · Block Contract · Cookbook Slider