# Formulários e overrides

> Formulários derivados da metadata com overrides pontuais — checkbox com valores de domínio, grupos, opções remotas dependentes e filtros de referência.

O formulário de uma coleção é derivado de `/core/models/:model`. `form` funciona como **override pontual**: campos não informados continuam sendo gerados automaticamente.

```tsx
<CoreCollection
  model="ClienteFornecedor"
  endpoint="/clientes-fornecedores"
  form={[
    { field: "cliente", label: "Cliente", widget: "checkbox", checkedValue: "S", uncheckedValue: "N",
      group: "classificacao", groupLabel: "Classificação", groupDescription: "Marque uma ou as duas opções.", inline: true },
    { field: "fornecedor", label: "Fornecedor", widget: "checkbox", checkedValue: "S", uncheckedValue: "N",
      group: "classificacao", inline: true },
  ]}
/>
```

Resultado:

```txt
Classificação
Marque uma ou as duas opções.

[✓] Cliente    [ ] Fornecedor
```

## Referência de `OonFormFieldDef`

| Propriedade | Descrição |
|---|---|
| `field` | **Obrigatório.** Campo da model |
| `label`, `kind`, `required`, `readonly`, `ref` | Sobrescrevem a metadata |
| `options` | Opções fixas (`string` ou `{ value, label, description? }`) |
| `widget` | `default` ou `checkbox` |
| `checkedValue`, `uncheckedValue` | Valores persistidos do checkbox (padrão `true`/`false`) |
| `group`, `groupLabel`, `groupDescription`, `inline` | Agrupamento visual |
| `renderer` | Renderer de `components.fieldRenderers` |
| `permissions`, `capabilities` | Exibição condicional |

## Opções remotas dependentes

Campos `enum` podem carregar opções de um endpoint dependente dos valores do formulário e do registro pai:

```ts
{
  field: "roleCode",
  kind: "enum",
  optionsEndpoint: "/control-plane/app-role-catalogs/:appId?tenantId=:parentId",
  optionsResponsePath: "options",
  optionsValueField: "value",
  optionsLabelField: "label",
  optionsEditablePath: "editable",
  optionsDependsOn: ["appId"],
  fallbackOptions: [{ value: "admin", label: "Administrador" }],
  readonlyOnFallback: true,
  optionsUnavailableMessage: "Catálogo indisponível; usando perfil padrão.",
}
```

- Tokens `:campo`, `:parentId` e `:parent.campo` são interpolados com URL encoding.
- Alterar um campo de `optionsDependsOn` limpa a seleção e recarrega o catálogo.
- Se a consulta falhar ou vier vazia, `fallbackOptions` é usado; por padrão o controle fica bloqueado durante o fallback.

## Referências filtradas (esteiras)

```ts
{ field: "estadoId", referenceFilters: { status: "Ativo" } },
{ field: "cidadeId", referenceFilters: { status: "Ativo" },
  referenceFilterFrom: { estadoId: "estadoId" },
  referenceDisabledMessage: "Selecione primeiro o estado." }
```

## Campos relacionados (`ref`)

São renderizados como caixas de seleção pesquisáveis: o usuário abre a lista completa ou digita para filtrar no backend. Ao editar relações armazenadas apenas como ObjectId, o formulário busca o registro atual para exibir o rótulo.

## Fórmulas na tela

Campos `computed` são recalculados em tempo real e não são enviados no payload. Veja [Fórmulas e validações](/docs/backend/formulas-e-validacoes#previa-reativa-no-frontend).

> [!TIP]
> Não crie uma página React, um formulário completo ou um renderer só para trocar um controle, agrupar campos ou carregar opções remotas — os overrides resolvem.

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