# Shell e layouts

> Variações do shell do Core, slots de layout, layouts por rota e páginas por blocos declarativos.

O shell — cabeçalho, menu lateral, área principal, estados de sessão — pertence ao Core. Você o configura, não o reimplementa.

## Configuração do shell

```tsx
defineOonApp({
  // ...
  shell: {
    shell: "default",     // "default" | "portal" | "content-only" | "custom:<chave>"
    sidebar: "core",      // "core" | "none" | "custom:<chave>"
    topbar: "core",
    header: "none",       // "none" | "custom:<chave>"
    footer: "none",       // "core" | "none" | "custom:<chave>"
    assistant: "none",    // "core" | "none" | "custom:<chave>"
  },
});
```

| Shell | Uso |
|---|---|
| `default` | Central operacional com menu lateral e cabeçalho |
| `portal` | Portais e cockpits |
| `content-only` | Apenas a área de conteúdo |
| `custom:<chave>` | Componente registrado em `layouts` |

## Slots de layout

```tsx
import { ThemeToggle } from "../components/ThemeToggle";
import { OrgSwitcher } from "../components/OrgSwitcher";

defineOonApp({
  // ...
  layouts: {
    topbarEnd: ThemeToggle,   // à direita do avatar no cabeçalho
    organization: OrgSwitcher, // seletor de organização no cabeçalho
  },
});
```

Os slots recebem `{ app, menu }`. Para o seletor de organização, use `CoreOrganizationSwitcher` do [UI Kit](/docs/frontend/ui-kit).

## Layout por rota

```tsx
function WorkspaceLayout({ children }: { children: React.ReactNode }) {
  return <div className="workspace">{children}</div>;
}

defineOonRoutes([{ path: "/pedidos", component: PedidosPage, layout: WorkspaceLayout }]);
```

O layout envolve **somente** a rota declarada, dentro do shell.

## Páginas por blocos

Para telas simples, declare blocos em vez de escrever React:

```tsx
defineOonApp({
  // ...
  pages: [
    {
      path: "/inicio",
      label: "Início",
      section: "Visão geral",
      blocks: [
        { type: "markdown", content: "## Bem-vindo\nAcompanhe a operação do dia." },
        { type: "navigation.cards", columns: 3, cards: [
          { title: "Pedidos", description: "Acompanhe pedidos", href: "/pedidos" },
          { title: "Fornecedores", href: "/fornecedores" },
        ] },
        { type: "collection.datagrid", model: "Pedido", mode: "dynamic" },
        { type: "custom", component: "GraficoMensal" },
      ],
    },
  ],
  components: { pageComponents: { GraficoMensal } },
});
```

| Bloco | Descrição |
|---|---|
| `markdown` | Texto em Markdown |
| `section` | Agrupa blocos com título e descrição |
| `navigation.cards` | Cards de navegação (1–4 colunas) |
| `collection.datagrid` | Grid de uma model |
| `collection.cards` | Cards de uma model |
| `custom` | Componente de `pageComponents` |
| `collection.form`, `pipeline.board`, `document.viewer`, `dashboard.kpi`, `tabs` | Blocos genéricos |

Páginas aceitam `public`, `layout` (`default`, `content-only`, `portal`), `permissions`, `capabilities`, `hidden` e `order`. Páginas ocultas continuam acessíveis por ações do shell (por exemplo, `/configuracoes` aberta pelo ícone de engrenagem).

## Regra de ouro

Não recrie shell, menu, roteamento e providers. Overrides são para: campo especial, ação específica, card, cabeçalho, dashboard, integração visual pontual ou aba customizada da modal de detalhe.

Fonte: https://sdk.oonapps.com/docs/frontend/shell-e-layouts