Grade de produtos com blocos de catálogo

Quero que o lojista monte o card do produto no editor (imagem, título, descrição, preço, botão) e que cada produto da grade use a mesma composição. Remover um bloco remove aquele elemento de todos os cards.

Referência de implementação: tema de exemplo com seção main + blocos catalog-product-* + lib/renderCatalogProductBlocks.jsx. Índice: Cookbooks

Runtime Corvex, não motor interno

Grade com blocos nos cards é um caso de uso suportado de ponta a ponta: o lojista edita blocos na section; cada produto repete o mesmo molde; preview no builder e vitrine publicada batem. No código do tema você usa @corvex/runtime e @corvex/theme-sdk. O editor entrega o molde em blocks e block_order. O tema não importa o motor do editor. Ferramentas usuais para este cookbook:

Ferramenta	Papel
`useSectionBlockTemplate`	Molde `blocks` + `block_order` ao vivo no builder
`RepeatedBlockCard`	Card âncora (`editorHost`) + espelho (`renderMirror`) na grade
`renderCatalogProductBlocks` (no tema)	Mapa `type` → componente + ordem por produto
`useSectionLiveBlocks`	Alternativa de baixo nível se o layout do card for custom

Quando usar este padrão

Objetivo	Use
Card fixo, rápido, mesmo layout em várias seções	Product Card (snippet)
Um slide / um ícone / um item de FAQ por bloco	Runtime API — Padrão A (`SectionBlockCanvas` + `{children}`)
Marquee ou carrossel montado só de settings, sem card no DOM	Runtime API — Padrão B (`useSectionLiveBlocks`)
Grade de produtos com card editável bloco a bloco	Este cookbook (Padrão C) — `useSectionBlockTemplate` + `RepeatedBlockCard`

Três camadas (não misture)

Section (main)
  ├── settings     → título da grade, colunas, filtros, coleção
  ├── data / fetch → useCorvexData('products') ou defineSectionData
  └── blocks       → “molde” do card (tipos + settings), repetido por produto

Snippet (product-card)
  └── UI fixa; import @corvex/snippets/product-card; NÃO aparece na árvore de blocos

Block catalog-product-*
  └── Uma “fatia” do card; lê o produto atual via contexto; settings só de apresentação

Snippets não viram blocos sozinhos. Para card composável, crie tipos de block dedicados (ou um block único que importa o snippet internamente — o lojista ainda não desmonta o card no editor).

Contratos utilizados

Section — blocks.json, props blocks / block_order
Block — settings; sem fetch de catálogo
Product — campos públicos no card
Runtime API — useSectionBlockTemplate, RepeatedBlockCard, useEditorPreviewCanvas, BlockChrome
Theme defaults — templates/*.json com blocks + block_order

Anatomia recomendada no tema

sections/main/
  section.jsx       # loop de produtos + RepeatedBlockCard no builder
  schema.json
  blocks.json       # tipos permitidos + max_blocks
  styles.css

blocks/catalog-product-image/
  block.jsx         # useCatalogProduct() + Image
  schema.json       # type: catalog-product-image, name: Imagem do produto

blocks/catalog-product-title/
  ...

lib/catalogProductContext.jsx   # Provider por produto na grade
lib/renderCatalogProductBlocks.jsx  # map type → componente + ordem
lib/catalogProduct.js             # helpers (preço, imagem, descrição)

Registre cada catalog-product-* em theme.json → blocks[].

1. `blocks.json` da section

Um tipo por “fatia” do card. max_blocks = quantidade de tipos distintos (não repita o mesmo tipo várias vezes no manifest se cada fatia é única).

{
  "blocks": [
    { "type": "catalog-product-image" },
    { "type": "catalog-product-title" },
    { "type": "catalog-product-description" },
    { "type": "catalog-product-price" },
    { "type": "catalog-product-button" }
  ],
  "max_blocks": 5
}

O rótulo de cada bloco vem de blocks/{id}/schema.json → name, não deste arquivo. O build anexa o manifest no componente da section. Não importe blocks.json no JSX.

2. Block — receber produto sem fetch

import { BlockChrome } from '@corvex/runtime';
import { useCatalogProduct } from '../../lib/catalogProductContext.jsx';

export default function CatalogProductTitleBlock({ settings = {}, product: productProp }) {
  const product = useCatalogProduct(productProp);
  const title = product?.title || 'Nome do produto';
  // settings: cor, alinhamento, etc.
  return (
    <BlockChrome label="Título do produto">
      <h2>{title}</h2>
    </BlockChrome>
  );
}

O tipo é o id da pasta (blocks/catalog-product-title/). Se schema.json tiver type, use o mesmo id. O validador não exige type.
name no schema é o rótulo do bloco no editor. Pode mudar. Não mude a pasta depois que a página já existe.

3. Section — loop + render repetido

import { useMemo } from 'react';
import {
  RepeatedBlockCard,
  SectionChrome,
  useEditorPreviewCanvas,
  useSectionBlockTemplate,
} from '@corvex/runtime';
import { useCorvexData } from '@corvex/theme-sdk';
import { CatalogProductProvider } from '../../lib/catalogProductContext.jsx';
import {
  renderCatalogProductBlocks,
  resolveCatalogBlocks,
} from '../../lib/renderCatalogProductBlocks.jsx';

export default function MainSection({
  settings = {},
  blocks = {},
  block_order = [],
  children,
}) {
  const inBuilder = useEditorPreviewCanvas();
  const blockTemplate = useSectionBlockTemplate(blocks, block_order);
  const catalogBlocks = useMemo(
    () => resolveCatalogBlocks(blockTemplate.blocks, blockTemplate.block_order),
    [blockTemplate.blocks, blockTemplate.block_order]
  );
  const { data } = useCorvexData('products', { /* filtros da section */ });
  const products = normalizeProducts(data);

  return (
    <SectionChrome settings={settings}>
      <ul>
        {inBuilder && products.length === 0 ? (
          <li>
            <CatalogProductProvider product={null}>
              <RepeatedBlockCard editorHost>{children}</RepeatedBlockCard>
            </CatalogProductProvider>
          </li>
        ) : null}
        {products.map((product, index) => (
          <li key={product.id}>
            <CatalogProductProvider product={product}>
              <RepeatedBlockCard
                editorHost={inBuilder && index === 0}
                renderMirror={() =>
                  renderCatalogProductBlocks(
                    product,
                    catalogBlocks.blocks,
                    catalogBlocks.block_order,
                    { /* ações */ }
                  )
                }
              >
                {children}
              </RepeatedBlockCard>
            </CatalogProductProvider>
          </li>
        ))}
      </ul>
    </SectionChrome>
  );
}

Pontos obrigatórios:

Vitrine: renderCatalogProductBlocks (ou equivalente) em cada produto — mesma block_order.
Builder: use RepeatedBlockCard com editorHost no primeiro card (ou no lugar vazio, se não houver produtos) e renderMirror nos demais. Não monte os cards à mão a partir de blocks no iframe.
Molde ao vivo: useSectionBlockTemplate(blocks, block_order) devolve blocks e block_order atualizados no builder.
Persistência: blocks e block_order nos props da section (template e publicação). O editor atualiza esses props ao editar, reordenar e remover itens.

Fronteira do tema: não importe o motor do editor, não declare propriedade estática no componente e não importe código interno da plataforma. A integração com o builder passa por @corvex/runtime.

4. `renderCatalogProductBlocks`

Mapa explícito type → componente; itere block_order, nunca Object.keys sem ordem.

const BLOCK_COMPONENTS = {
  'catalog-product-image': CatalogProductImageBlock,
  'catalog-product-title': CatalogProductTitleBlock,
  // ...
};

export function renderCatalogProductBlocks(product, blocks, block_order, actions = {}) {
  const order = block_order?.length ? block_order : Object.keys(blocks || {});
  return order
    .map((id) => {
      const entry = blocks[id];
      const Component = BLOCK_COMPONENTS[entry?.type];
      if (!Component) return null;
      return (
        <Component
          key={`${product.id}-${id}`}
          settings={entry.settings || {}}
          product={product}
          {...actions}
        />
      );
    })
    .filter(Boolean);
}

resolveCatalogBlocks pode definir defaults quando blocks está vazio (primeira instalação).

5. Persistência e templates

Camada	Onde	O que guarda
Theme defaults	`templates/index.json` (etc.)	`sections.main.blocks`, `block_order`, `settings`
Merchant	Editor → Publish	Mesma forma no JSON da loja
Editor ao vivo	Árvore de blocos da section	Sincronizada em `props.blocks` / `props.block_order`

Checklist de template: se order inclui "main", a chave sections.main deve existir com blocks + block_order. Referência: templates/search.json no tema de exemplo.

6. O que fazer / o que não fazer

Faça

Um block por fatia do card. O tipo é a pasta (catalog-product-title). schema.type, se existir, repete esse id.
Provider de produto por item da grade (CatalogProductProvider).
block_order como fonte de ordem na vitrine e no editor.
useSectionBlockTemplate + RepeatedBlockCard (ou composição equivalente com useSectionLiveBlocks + SectionBlockCanvas se o layout exigir).
Defaults completos no template para a seção aparecer correta ao adicionar na página.

Não faça

Usar snippet product-card na mesma seção e esperar que blocos do editor alterem o snippet.
Assumir que product-list (carrossel com snippet) compartilha blocos com main.
Fetch de produtos dentro do block (storefront.products.get no block).
Montar {children} duas vezes na grade visível (ghost blocks).
Fallback que renderiza 5 imagens quando o tipo do block não resolve — corrija type no molde (useSectionBlockTemplate / props da section).
Esconder fatia só com toggle mostrar: false se a intenção é remover a fatia do card — prefira remover o bloco na árvore (toggle é opcional para o lojista).

7. Sintomas comuns

Sintoma	Causa provável
Vários blocos viram só imagem	`blocks[id].type` errado (todos `catalog-product-image`); re-adicione blocos após corrigir editor/plataforma
Remover título e ficar 2 imagens	Mesmo problema de `type`
Mudança na árvore não reflete na grade	Section sem proxy do runtime (`useSectionBlockTemplate` / `RepeatedBlockCard`); atualize o editor e o tema
Selecionar bloco mostra label flutuante / fora do card	`{children}` em host oculto; use `RepeatedBlockCard` com `editorHost` no primeiro card da grade
Blocos não aparecem ao adicionar seção	Template sem `sections.{id}.blocks`
Card diferente na home vs busca	Templates diferentes — alinhe defaults

8. Checklist antes de publicar o tema

sections/{id}/blocks.json + ids em theme.json → blocks[]
Cada bloco na pasta blocks/{id}/; name pode mudar, a pasta não
Section com data ou useCorvexData para produtos
renderCatalogProductBlocks (ou equivalente) + contexto de produto
RepeatedBlockCard (ou equivalente documentado) no builder
Templates com blocks + block_order para a section de grade
corvex validate . e corvex build .
Teste no editor: adicionar/remover/reordenar blocos e conferir todos os cards da grade

Introdução

Temas

Seções

Guias

Exemplos

Storefront Components

Schema

CLI

Dados

SDK

Contratos

Marketplace

Grade de produtos com blocos de catálogo

Grade de produtos com blocos de catálogo

Runtime Corvex, não motor interno

Quando usar este padrão

Três camadas (não misture)

Contratos utilizados

Anatomia recomendada no tema

1. `blocks.json` da section

2. Block — receber produto sem fetch

3. Section — loop + render repetido

4. `renderCatalogProductBlocks`

5. Persistência e templates

6. O que fazer / o que não fazer

Faça

Não faça

7. Sintomas comuns

8. Checklist antes de publicar o tema

Relacionados

​Grade de produtos com blocos de catálogo

​Runtime Corvex, não motor interno

​Quando usar este padrão

​Três camadas (não misture)

​Contratos utilizados

​Anatomia recomendada no tema

​1. blocks.json da section

​2. Block — receber produto sem fetch

​3. Section — loop + render repetido

​4. renderCatalogProductBlocks

​5. Persistência e templates

​6. O que fazer / o que não fazer

​Faça

​Não faça

​7. Sintomas comuns

​8. Checklist antes de publicar o tema

​Relacionados

Grade de produtos com blocos de catálogo

Runtime Corvex, não motor interno

Quando usar este padrão

Três camadas (não misture)

Contratos utilizados

Anatomia recomendada no tema

1. `blocks.json` da section

2. Block — receber produto sem fetch

3. Section — loop + render repetido

4. `renderCatalogProductBlocks`

5. Persistência e templates

6. O que fazer / o que não fazer

Faça

Não faça

7. Sintomas comuns

8. Checklist antes de publicar o tema

Relacionados