# Coleções (CoreCollection)

> Grid, busca, filtros, formulário derivado da metadata, ações por linha, import/export e modal de detalhe — como componente ou como view declarativa.

`CoreCollection` monta uma tela operacional completa a partir da metadata de uma model.

```tsx title="frontend/src/pages/PedidosPage.tsx"
import { CoreCollection } from "@oondemand/oon-core-front";

export function PedidosPage() {
  return (
    <CoreCollection
      model="Pedido"
      label="Pedidos"
      endpoint="/pedidos"
      importExport
      list={{
        filters: [
          { field: "status", label: "Status", type: "select", options: [
            { label: "Todos", value: "" }, { label: "Aprovados", value: "Aprovado" },
          ] },
          { field: "fornecedor", label: "Fornecedor", type: "ref" },
        ],
        columns: ["numero", "fornecedor", { field: "valor", format: "currency" }, { field: "status", format: "badge" }],
        rowActions: [{ type: "openDetailModal", label: "Abrir", icon: "edit", initialTab: "resumo" }],
      }}
    />
  );
}
```

## Props

| Prop | Descrição |
|---|---|
| `model` | **Obrigatório.** Nome da model no backend |
| `label`, `section` | Título e seção |
| `endpoint` | `basePath` do CRUD (ex.: `/pedidos`) |
| `mode` | `dynamic` (padrão — tudo da metadata), `minimal` ou `full` (colunas explícitas) |
| `columns` | Colunas no modo `full` |
| `form` | Overrides pontuais de campos — veja [Formulários](/docs/frontend/formularios) |
| `importExport` | Liga importação e exportação |
| `list` | `filters`, `columns`, `rowActions`, `builtInActions` |
| `relations` | Relações nomeadas reutilizáveis |
| `detailModal` | Modal com abas — veja [Modal de detalhe](/docs/frontend/modal-de-detalhe) |
| `cellRenderers`, `registry` | Renderers customizados |

## Colunas

```ts
{ field: "valor", label: "Valor", format: "currency", sortable: true, width: 140, renderer: "valorComAlerta", permissions: ["pedidos.finance"] }
```

Formatos: `text`, `number`, `currency`, `percent`, `date`, `datetime`, `badge`.

## Filtros

| `type` | Controle |
|---|---|
| `text` | Texto livre |
| `select` | Opções fixas |
| `date`, `dateRange` | Data |
| `numberRange` | Faixa numérica |
| `boolean` | Sim/não |
| `ref` | Seletor pesquisável de outra model |

Os valores viram query parameters do CRUD (filtros de igualdade).

## Ações nativas

`builtInActions: { create: false, edit: false, delete: false }` oculta as ações CRUD quando a Central oferece ações de negócio próprias.

## Como view declarativa

Para telas simples, declare a coleção como view — o Core cria rota e item de menu:

```tsx
import { defineCollectionView, defineOonApp } from "@oondemand/oon-core-front";

export const app = defineOonApp({
  // ...
  ui: {
    views: [
      defineCollectionView({ model: "Fornecedor", label: "Fornecedores", path: "/fornecedores", section: "Cadastros", mode: "dynamic", permissions: ["fornecedores.read"] }),
    ],
  },
});
```

`hidden: true` mantém a rota e remove a coleção do menu.

## Padrão de tela operacional

```txt
Título · Filtros · Busca · Botão novo · Grid principal · Ações por linha
```

A tela principal não deve acumular detalhe de filhos, formulários longos ou fluxos complexos abaixo do grid. Use a modal de detalhe.

## Regra de ouro

Antes de criar uma página React customizada, verifique se a necessidade cabe em:

1. views `collection`;
2. `list.filters` e `list.rowActions`;
3. `detailModal.tabs`;
4. `form.groups`;
5. `relatedGrid`;
6. `rowActions` declarativas;
7. um pequeno `customComponent` isolado.

Código customizado de página inteira é a última opção.

Fonte: https://sdk.oonapps.com/docs/frontend/colecoes