Docs › Frontend

Rotas e navegação

defineOonRoutes e defineOonNavigation — rotas com guards de permissão, lazy loading, layouts por rota, rotas públicas, rotas reservadas e menu por seções.

Rotas

import { defineOonRoutes } from "@oondemand/oon-core-front/routing";
import { HomePage } from "../pages/HomePage";
import { WorkspaceLayout } from "../layouts/WorkspaceLayout";

export const routes = defineOonRoutes([
  { path: "/", component: HomePage },
  {
    path: "/pedidos",
    lazy: () => import("../pages/PedidosPage"),
    layout: WorkspaceLayout,
    permissions: ["pedidos.read"],
  },
  { path: "/relatorios", element: <RelatoriosPage />, capabilities: ["core.transactional-email"] },
]);
Propriedade Descrição
path Caminho absoluto iniciado por /
component Página React instanciada pelo roteador
element Elemento já construído
lazy () => import("./Pagina") com export default — code splitting
layout Componente { children } aplicado só a essa rota
permissions Guard: exige qualquer uma das permissões
capabilities Guard por capability declarada
public Rota fora do guard de autenticação e do shell

Cada rota declara exatamente uma fonte: element, component ou lazy. Caminhos duplicados são rejeitados.

Rotas públicas

{ path: "/status", component: StatusPage, public: true }

Rotas public são renderizadas fora do ActivationGuard, do AppAccessGuard e do shell autenticado — úteis para páginas de status, landing pages ou portais. Este site é um exemplo: todo ele é composto por rotas públicas de um App Oon.

Rotas reservadas

Pertencem ao Core e não podem ser declaradas: /login, /accept-invite, /first-access, /ativacao, /instancia-suspensa, /instancia-revogada, /acesso-negado. A lista está em OON_RESERVED_ROUTES.

Para personalizar o login de um portal, use systemPages: { login: MinhaPaginaDeLogin } — substitui o conteúdo e mantém rota e guards com o Core.

import { defineOonNavigation } from "@oondemand/oon-core-front/routing";

export const navigation = defineOonNavigation([
  { label: "Início", href: "/", order: 10 },
  { label: "Pedidos", href: "/pedidos", section: "Operação", order: 20, permissions: ["pedidos.read"] },
  { label: "Aprovações", href: "/aprovacoes", section: "Operação", order: 30, requires: "temAprovacoes", badge: 3 },
  { label: "Documentação", href: "https://exemplo.com/docs", external: true, action: "user-menu" },
]);
Propriedade Descrição
label Obrigatório
href Absoluto (/…) ou externo com external: true
section Agrupa itens no menu lateral
order Ordem dentro da seção
permissions, capabilities Esconde o item sem a permissão/capability
requires Nome de uma condição em components.menuConditions
children Submenu
badge, icon, hidden Apresentação
action "user-menu" move o item para o menu do avatar; "profile" define "Meu perfil"

Cada item precisa de href, action ou children.

Condições de visibilidade

export const app = defineOonApp({
  // ...
  components: {
    menuConditions: {
      temAprovacoes: () => useAprovacoesPendentes() > 0, // hook React sem argumentos
    },
  },
});

Quando todos os itens de uma seção dependem de condições falsas, a seção inteira some. Os hooks são chamados sempre na mesma ordem a cada render do menu.

Comportamento do menu

  • Seções com order respeitado e aria-current no item ativo.
  • No celular, o menu vira gaveta aberta pelo cabeçalho.
  • Itens action: "user-menu" aparecem no menu do avatar — veja abaixo.
  • Versões ficam no "Sobre" (tooltip do título), fora da tela principal.

Itens com action: "user-menu" saem do menu lateral e vão para o menu do avatar, entre "Meu perfil" e "Sair". Desde a 0.7.39, eles são agrupados por section: cada grupo tem título e separador, os grupos seguem a ordem do primeiro item e, dentro de cada grupo, vale order. Itens sem section formam um grupo sem título.

defineOonNavigation([
  { label: "Preferências", href: "/preferencias", section: "Conta", order: 10, action: "user-menu" },
  { label: "Usuários e Acessos", href: "/usuarios-acessos", section: "Configurações", order: 60, permissions: ["users.read"], action: "user-menu" },
  { label: "Central de ajuda", href: "https://ajuda.exemplo.com", external: true, action: "user-menu" },
]);

Reposicionar itens do Core

O Core adiciona itens próprios ao menu — Usuários e Acessos (/usuarios-acessos) e E-mail transacional (/configuracoes/email-transacional). Desde a 0.7.39, um item de navegação do App com o mesmo href substitui o item padrão: você escolhe seção, ordem, rótulo ou o menu do usuário, e a rota e a página continuam sendo as do Core. Mantenha as mesmas permissions do item original (users.read, transactional-email.config.read).