# API pública do `@oondemand/oon-core-front`

O contrato principal do frontend é code-first.

## Bootstrap

- `defineOonApp`: define identidade, API, rotas, navegação, shell, layouts, páginas, componentes e temas.
- `startOonApp`: valida e monta o App React.
- `defineOonRoutes`, `defineOonNavigation`: helpers tipados para composição local.

## Subpaths públicos

- `/ui`: primitives, padrões e componentes de domínio;
- `/routing`: rotas, navegação e helpers;
- `/theme`: temas, tokens e seleção em runtime;
- `/hooks`: hooks de autenticação, tenant, API e metadata;
- `/testing`: utilitários de teste.

## Segurança

- `useOonAuth`, `can`, `PermissionGate`, `Can`: permissões resolvidas pelo backend;
- `useOonTenant`, `createTenantStorage`: contexto tenant quando aplicável;
- `useOonApi`, `useOonResource`, `useCoreMetadata`, `useModelSchema`: acesso padronizado;
- rotas reservadas e guards obrigatórios pertencem ao Core.

## Contexto e descarte de estado por tenant

`useOonTenant()` devolve `{activeTenantId: string | null, switchTenant(id), clearTenant()}`
em Apps com tenancy. Não chame esse hook em Apps `tenancyModel=none`.
O Core atualiza o header e limpa o cache de queries na troca. Estado React local,
formulários, tokens de uso único e respostas assíncronas também devem ser descartados:
uma página filha com `key={activeTenantId ?? "no-tenant"}` é uma composição possível.
`useOonAuth().hasPermission(code)` permite ocultar ações, com autorização obrigatória
e independente no backend. `useOonApi()` fornece `{http}` para o cliente autenticado.

## Domínio e UI

Views declarativas continuam disponíveis como composição opcional dentro do
objeto App. Componentes, páginas e layouts locais podem ser usados em qualquer
`appKind`. Consulte `FRONTEND_CODE_FIRST.md`.