sass-imobiliaria/specs/030-navbar-topo-ux/data-model.md

Data Model — 030-navbar-topo-ux

Esta feature não cria entidades de banco nem migrations. O modelo abaixo descreve dados de sessão já existentes e o estado de UI necessário para a navbar.

---

1. Entidades Existentes Consumidas

AuthSession

Fonte: frontend/src/contexts/AuthContext.tsx

Campo	Tipo	Origem	Uso na navbar
user	`User	null`	contexto de autenticação
token	`string	null`	localStorage + contexto
isAuthenticated	boolean	derivado do contexto	Liga/desliga ações de visitante vs cliente/admin
isLoading	boolean	bootstrap da sessão	Evita flicker de ações incorretas durante hidratação
logout()	() => void	contexto	Encerra sessão e força retorno visual ao estado visitante

UserProfile

Fonte: tipo User retornado pelo fluxo de auth atual.

Campo	Tipo	Regra	Uso na navbar
name	string	obrigatório quando user != null	Exibe inicial e primeiro nome truncado
role	string	valor relevante nesta feature: admin ou não-admin	Controla presença do menu Admin e do menu Minha Conta

Invariantes:

• user === null implica navbar de visitante.
• user.role === 'admin' implica ausência do menu de cliente padrão.
• Nome longo nunca deve quebrar layout; deve ser truncado no gatilho.

---

2. Entidades de Navegação

NavItem

Representa um item navegável exibido em um dos grupos da navbar.

interface NavItem {
  label: string
  to: string
  end?: boolean
  visibility: 'public' | 'client' | 'admin'
  group: 'primary' | 'contextual' | 'cta'
}

Regras:

• Itens public aparecem para todos, salvo ajustes de prioridade visual.
• Itens client aparecem apenas quando isAuthenticated === true e role !== 'admin'.
• Itens admin aparecem apenas quando role === 'admin'.
• group='cta' não substitui o grupo público; ele complementa a hierarquia do topo.

ProfileSection

Agrupa ações contextuais por perfil no mobile e no desktop.

interface ProfileSection {
  id: 'admin' | 'client'
  title: string
  items: NavItem[]
  includesLogout: boolean
}

Regras:

• No mobile, cada seção deve aparecer com cabeçalho próprio.
• Logout deve permanecer visualmente separado das ações de navegação.

---

3. Estado Transitório de UI

NavUIState

Modelo recomendado para governar interações mutuamente exclusivas.

type ActiveOverlay = 'closed' | 'mobile' | 'admin' | 'client'

interface NavUIState {
  activeOverlay: ActiveOverlay
  isDesktop: boolean
}

Regras de transição:

Evento	Estado atual	Próximo estado	Observação
Clique no hambúrguer	closed	mobile	Só em mobile
Clique no hambúrguer	mobile	closed	Toggle padrão
Clique no gatilho Admin	closed ou client	admin	Fecha qualquer outro overlay
Clique no gatilho Cliente	closed ou admin	client	Fecha qualquer outro overlay
Clique fora	mobile / admin / client	closed	Requisito FR-012
Mudança de rota	qualquer	closed	Requisito FR-013
Logout confirmado	qualquer	closed	Navbar volta ao estado visitante
Escape	mobile / admin / client	closed	Recomendado para previsibilidade

Invariantes:

• Apenas um contexto pode permanecer aberto por vez.
• mobile não pode coexistir com admin ou client.
• admin e client são mutuamente exclusivos.

---

4. Estados Derivados de Exibição

NavbarVariant

type NavbarVariant = 'visitor' | 'client' | 'admin'

Derivação:

• visitor: !isLoading && !isAuthenticated
• client: isAuthenticated && user?.role !== 'admin'
• admin: isAuthenticated && user?.role === 'admin'

ActiveLinkState

Estado derivado de NavLink/rota atual.

Regras:

• Links públicos devem refletir estado ativo em desktop e mobile.
• Rotas com query string, como /imoveis?listing_type=venda, devem manter coerência visual com a intenção do link.
• Itens contextuais devem fechar o menu após navegação bem-sucedida.

---

5. Regras de Validação de UX/A11y

Regra	Aplicação
aria-expanded coerente	gatilhos do menu mobile e dropdowns
aria-controls presente	menu hambúrguer e, se aplicável, painéis contextuais
foco visível	todos os links e botões interativos
alvo mínimo 44x44	hambúrguer, CTA, itens tocáveis em mobile
truncamento elegante	nome do usuário e gatilhos de perfil

---

6. Relações Entre Entidades

AuthSession
  └── UserProfile
        ├── role ──────────────┐
        └── name ───────┐      │
                        │      │
NavbarVariant <─────────┘      │
                               │
NavItem.visibility ────────────┘

NavUIState.activeOverlay
  ├── controls mobile menu visibility
  ├── controls admin dropdown visibility
  └── controls client dropdown visibility