Header

Cookbook — header com menu, color scheme, layout group e carrinho.

Quero um header com logo, menu publicado e carrinho. Qual é a implementação recomendada?

Código de referência validado: seu tema (adaptado do cookbook)

Índice: Cookbooks

---

Contratos utilizados

• Section Contract
• Schema Contract
• Theme Contract — layoutGroups
• Field menu — valor persistido = handle
• Field color_scheme — valor persistido = scheme id
• Field image — logo opcional
• Cart Contract — useCorvexCart()
• Data — menus

---

Objetivo

Header global com:

• logo (texto ou imagem)
• menu resolvido via handle (settings.menu)
• link do carrinho com contagem
• esquema de cores aplicado ao subtree
• menu mobile simples (toggle, sem mega menu)

O header entra via layout group — não duplique em cada template.

---

Arquivos

sections/cookbook-header/
├── section.jsx
├── schema.json
└── styles.css

groups/header.json          # defaults do layout group
theme.json                  # layoutGroups.header → cookbook-header
config/settings.schema.json # color_schemes para color_scheme field

---

Schema

settings.menu persiste o handle (ex.: "main"), não o objeto do menu.

{
  "id": "menu",
  "type": "menu",
  "label": "Menu principal",
  "default": "main"
}

Ver referência completa: menu.

---

Resolver o menu (handle → links)

import { useStorefrontMenus, StorefrontNav } from '@corvex/runtime';

const menuHandle = settings.menu || 'main';
const { getMenu, loading } = useStorefrontMenus([menuHandle]);
const menu = getMenu(menuHandle);

<StorefrontNav
  menu={menu}
  emptyFallback={<span>{loading ? 'Carregando…' : 'Menu não publicado'}</span>}
/>

menu é o objeto público (items, label, handle) retornado pelo SDK após resolver o handle.

---

Color scheme na section

import { ColorSchemeScope, useThemeSettingsReader } from '@corvex/runtime';

const { settings: themeSettings, schema: themeSettingsSchema } =
  useThemeSettingsReader();

<ColorSchemeScope
  as="header"
  colorSchemeId={settings.colorScheme}
  themeSettings={themeSettings}
  themeSettingsSchema={themeSettingsSchema}
  style={{
    background: 'var(--color-background, #fff)',
    color: 'var(--color-text, #111827)',
  }}
>
  …
</ColorSchemeScope>

settings.colorScheme é o id do esquema (ex.: scheme-light), não o objeto de cores.

---

Layout group (global)

theme.json:

"layoutGroups": {
  "header": {
    "name": "Cabeçalho",
    "position": "before",
    "sections": ["cookbook-header"]
  }
}

groups/header.json define a instância padrão (menu main, logo, etc.). Ver Theme Contract.

---

Carrinho

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

const { itemCount } = useCorvexCart();

<a href="/cart">Carrinho ({itemCount})</a>

itemCount vem de useCorvexCart, o mesmo hook do drawer. Os dois leem o carrinho publicado pelo CorvexCartProvider. Este exemplo não abre o drawer. O link vai para /cart. Para abrir o painel, o tema precisa compartilhar o estado open, como o cookbook do drawer descreve.

Assinatura pública: Cart Contract.

---

Comportamento no Editor

• Field menu: picker de handles ou lista de menus do rascunho da loja.
• Field color_scheme: lista esquemas de config/settings.schema.json.
• Header aparece em todas as páginas via layout group (não no picker “Adicionar seção” do corpo).

---

Cuidados

• Não assumir settings.menu como array de links — sempre resolver via SDK.
• Não duplicar o header em templates/*.json se já está no layout group.
• Menu vazio: mostrar fallback; loja pode não ter menu publicado ainda.
• Mobile: estado useState local à instância do header (vários headers = vários toggles independentes).

---

Checklist

• menu field com default main
• useStorefrontMenus([handle]) + StorefrontNav
• layoutGroups.header em theme.json
• groups/header.json com instância padrão
• Somente field types Stable
• corvex validate passa

Implementação completa: seu tema (adaptado do cookbook).