cf5603243c
- feat(025): favoritos locais com FavoritesContext, HeartButton, PublicFavoritesPage
- feat(026): central de contatos admin (leads/contatos unificados)
- feat(027): configuração da página de contato via admin
- feat(028): trabalhe conosco - candidaturas com upload e admin
- feat(029): UX área do cliente - visitas, comparação, perfil
- feat(030): navbar UX - menu mobile, ThemeToggle, useFavorites
- feat(031): hero light/dark - imagens separadas por tema, upload, preview, seed
- feat(032): performance homepage - Promise.all parallel fetches, sessionStorage cache,
preload hero image, loading=lazy nos cards, useInView hook, will-change carrossel,
keyframes em index.css, AgentsCarousel e HomeScrollScene via props
- fix: light mode HomeScrollScene - gradiente, cores de texto, scroll hint
migrations: g1h2i3j4k5l6 (source em leads), h1i2j3k4l5m6 (contact_config),
i1j2k3l4m5n6 (job_applications), j2k3l4m5n6o7 (hero theme images)
261 lines
14 KiB
Markdown
261 lines
14 KiB
Markdown
# Tasks: Navbar Topo UX (030)
|
||
|
||
**Input**: Design documents de `specs/030-navbar-topo-ux/`
|
||
**Prerequisites**: plan.md ✅ · spec.md ✅ · research.md ✅ · data-model.md ✅ · quickstart.md ✅ · contracts/navbar-ui-contract.md ✅
|
||
**Branch**: `030-navbar-topo-ux`
|
||
|
||
## Format: `[ID] [P?] [Story?] Description`
|
||
|
||
- **[P]**: pode ser executada em paralelo quando tocar arquivos distintos e sem dependência de tarefa incompleta
|
||
- **[Story]**: user story correspondente (`US1`, `US2`, `US3`, `US4`, `US5`)
|
||
- Caminhos exatos incluídos em cada tarefa
|
||
|
||
**Tests**: a spec não pede suíte automatizada nova para esta feature. O guardrail executável mínimo é `npm run build` em `frontend/`, complementado pelo checklist manual de `quickstart.md`.
|
||
|
||
---
|
||
|
||
## Phase 1: Setup — Preparação da Navbar Compartilhada
|
||
|
||
**Purpose**: estabelecer a base visual e estrutural da navbar compartilhada antes da refatoração de estados e das variações por perfil.
|
||
|
||
- [X] T001 Consolidar a configuração de navegação compartilhada em `frontend/src/components/Navbar.tsx` com arrays tipados para links públicos, ações do cliente e atalhos admin, alinhados aos destinos definidos em `specs/030-navbar-topo-ux/contracts/navbar-ui-contract.md`
|
||
|
||
- [X] T002 [P] Preparar tokens utilitários da navbar fixa em `frontend/src/index.css` para backdrop, foco visível, estados hover/active/open, alvo mínimo de toque e contraste consistente em tema claro/escuro
|
||
|
||
**Checkpoint**: a base de navegação e os tokens visuais da navbar estão definidos sem introduzir novas dependências externas.
|
||
|
||
---
|
||
|
||
## Phase 2: Foundational — Estado e Shell Compartilhados
|
||
|
||
**Purpose**: implementar a infraestrutura de estado e shell que bloqueia todas as user stories da navbar.
|
||
|
||
**⚠️ CRÍTICO**: nenhuma user story deve avançar antes desta fase estar concluída.
|
||
|
||
- [X] T003 Implementar em `frontend/src/components/Navbar.tsx` a derivação explícita de variante `visitor` / `client` / `admin` a partir de `useAuth()` e centralizar a decisão de visibilidade dos blocos públicos, contextuais e de autenticação
|
||
|
||
- [X] T004 Implementar em `frontend/src/components/Navbar.tsx` um controlador único de overlay com os estados `closed`, `mobile`, `client` e `admin`, substituindo booleans soltos por handlers de abertura/fechamento mutuamente exclusivos
|
||
|
||
- [X] T005 [P] Integrar em `frontend/src/components/Navbar.tsx` e `frontend/src/contexts/AuthContext.tsx` o fechamento global por mudança de rota, clique fora e logout, garantindo retorno imediato ao estado visual de visitante sem menus órfãos
|
||
|
||
- [X] T006 [P] Ajustar `frontend/src/layouts/ClientLayout.tsx` e `frontend/src/layouts/AdminLayout.tsx` para respeitar a altura e o empilhamento da navbar fixa sem sobrepor o conteúdo principal após a refatoração
|
||
|
||
**Checkpoint**: existe uma única fonte de verdade para os overlays da navbar, e os shells compartilham offset compatível com a barra fixa.
|
||
|
||
---
|
||
|
||
## Phase 3: User Story 1 — Navegação Principal Clara para Visitantes (Priority: P1) 🎯 MVP
|
||
|
||
**Goal**: entregar uma navbar pública clara, legível e consistente para visitantes em desktop e mobile.
|
||
|
||
**Independent Test**: em páginas públicas, o visitante vê até 5 links principais com estado ativo coerente, CTA `Anunciar imóvel`, ação `Entrar` e menu mobile com os mesmos destinos em ordem lógica.
|
||
|
||
- [X] T007 [US1] Reorganizar a estrutura desktop de visitante em `frontend/src/components/Navbar.tsx` para exibir logo, navegação pública principal, favoritos públicos quando aplicável, CTA `Anunciar imóvel` e ação `Entrar` com hierarquia visual clara
|
||
|
||
- [X] T008 [P] [US1] Implementar em `frontend/src/components/Navbar.tsx` a lógica de estado ativo para links públicos, incluindo correspondência coerente para rotas com query string como `/imoveis?listing_type=venda` e `/imoveis?listing_type=aluguel`
|
||
|
||
- [X] T009 [US1] Implementar o menu mobile de visitante em `frontend/src/components/Navbar.tsx` com gatilho hambúrguer, mesma ordem de destinos públicos do desktop, CTA destacado e fechamento automático ao navegar
|
||
|
||
- [X] T010 [P] [US1] Refinar em `frontend/src/index.css` a aparência da navegação pública desktop/mobile, do CTA principal e dos estados hover/active para manter legibilidade entre 320 px e 1440 px+
|
||
|
||
**Checkpoint**: US1 fica utilizável de forma independente para visitante em desktop e mobile, com destinos públicos claros e sem truncamento indevido.
|
||
|
||
---
|
||
|
||
## Phase 4: User Story 2 — Menu de Usuário Autenticado Orientado a Tarefas (Priority: P1)
|
||
|
||
**Goal**: permitir que o cliente autenticado acesse rapidamente ações pessoais e logout pela navbar.
|
||
|
||
**Independent Test**: ao autenticar como cliente não-admin, a navbar exibe gatilho de conta com nome truncado, dropdown com `Favoritos`, `Comparar`, `Visitas`, `Minha conta` e `Sair`, além da seção `Minha Conta` no mobile.
|
||
|
||
- [X] T011 [US2] Implementar em `frontend/src/components/Navbar.tsx` o gatilho de conta do cliente com inicial/avatar, primeiro nome truncado e dropdown desktop contendo `Favoritos`, `Comparar`, `Visitas`, `Minha conta` e `Sair` com separação visual do logout
|
||
|
||
- [X] T012 [P] [US2] Ajustar em `frontend/src/contexts/AuthContext.tsx` a superfície consumida pela navbar para suportar renderização confiável de nome, role e logout sem flicker durante hidratação ou encerramento de sessão
|
||
|
||
- [X] T013 [US2] Integrar em `frontend/src/components/Navbar.tsx` os links de `Favoritos` e `Comparar` com os contextos existentes `frontend/src/contexts/FavoritesContext.tsx` e `frontend/src/contexts/ComparisonContext.tsx` sem quebrar a navegação contextual do cliente
|
||
|
||
- [X] T014 [US2] Implementar em `frontend/src/components/Navbar.tsx` a seção mobile `Minha Conta` com os mesmos destinos do dropdown desktop, logout separado visualmente e fechamento automático após clique em qualquer ação
|
||
|
||
**Checkpoint**: US2 fica testável de forma independente com login de cliente, incluindo fluxo confiável de logout e paridade desktop/mobile.
|
||
|
||
---
|
||
|
||
## Phase 5: User Story 3 — Menu Admin com Acesso Rápido e Controle Visual (Priority: P1)
|
||
|
||
**Goal**: expor atalhos administrativos apenas para admins, sem poluir a experiência de visitantes e clientes.
|
||
|
||
**Independent Test**: ao autenticar como admin, a navbar exibe gatilho `Admin` com atalhos prioritários no desktop e seção `Admin` no mobile; para não-admin, nada disso aparece.
|
||
|
||
- [X] T015 [US3] Implementar em `frontend/src/components/Navbar.tsx` o gatilho e dropdown desktop `Admin`, exibindo apenas para `role === 'admin'` e listando os módulos existentes definidos em `specs/030-navbar-topo-ux/contracts/navbar-ui-contract.md`
|
||
|
||
- [X] T016 [US3] Implementar em `frontend/src/components/Navbar.tsx` a seção mobile `Admin` com os mesmos atalhos prioritários do desktop, mantendo exclusão do menu padrão `Minha Conta` para admins
|
||
|
||
- [X] T017 [P] [US3] Validar e ajustar em `frontend/src/App.tsx` os destinos usados pela navbar admin para garantir que todos os atalhos planejados apontem para rotas já existentes no SPA sem criar rotas novas fora do escopo
|
||
|
||
**Checkpoint**: US3 fica utilizável por admin sem regressão de visibilidade para visitante ou cliente autenticado.
|
||
|
||
---
|
||
|
||
## Phase 6: User Story 4 — Navbar Previsível, Acessível e Sem Conflitos de Estado (Priority: P2)
|
||
|
||
**Goal**: garantir previsibilidade de interação, acessibilidade básica e exclusão mútua robusta entre menu mobile, dropdown do cliente e dropdown admin.
|
||
|
||
**Independent Test**: abrir qualquer contexto e verificar fechamento por clique fora, Escape, mudança de rota e abertura de outro contexto; foco, labels e ARIA permanecem coerentes durante navegação por teclado.
|
||
|
||
- [X] T018 [US4] Aplicar em `frontend/src/components/Navbar.tsx` `aria-label`, `aria-expanded`, `aria-controls`, ids estáveis e suporte a `Enter`, `Espaço` e `Escape` para hambúrguer, dropdown do cliente e dropdown admin
|
||
|
||
- [X] T019 [P] [US4] Garantir em `frontend/src/index.css` foco visível, contraste acessível e alvo mínimo de 44x44 px para todos os gatilhos e itens clicáveis da navbar em desktop e mobile
|
||
|
||
- [X] T020 [US4] Consolidar em `frontend/src/components/Navbar.tsx` o fechamento mútuo entre `mobile`, `client` e `admin`, incluindo transições corretas ao trocar rota, clicar fora e executar logout com sucesso ou erro
|
||
|
||
**Checkpoint**: US4 fica validável com teclado e clique externo, sem estados simultâneos nem overlays presos.
|
||
|
||
---
|
||
|
||
## Phase 7: User Story 5 — Hierarquia Visual e Responsividade Premium (Priority: P2)
|
||
|
||
**Goal**: elevar a qualidade visual e a responsividade da navbar compartilhada em todos os breakpoints suportados.
|
||
|
||
**Independent Test**: a navbar permanece legível, sem sobreposição e com truncamento elegante de nomes longos em 320 px, 768 px, 1024 px e 1280 px+, nos dois temas.
|
||
|
||
- [X] T021 [US5] Reequilibrar em `frontend/src/components/Navbar.tsx` a distribuição entre logo, links públicos, ações contextuais, `ThemeToggle` e CTA para evitar sobreposição e excesso de densidade visual nos breakpoints principais
|
||
|
||
- [X] T022 [P] [US5] Ajustar em `frontend/src/index.css` truncamento elegante de nomes longos, espaçamento responsivo, microinterações curtas e separação visual entre navegação pública e contextual nos temas claro e escuro
|
||
|
||
- [X] T023 [US5] Revisar em `frontend/src/layouts/ClientLayout.tsx` e `frontend/src/layouts/AdminLayout.tsx` o comportamento do conteúdo após scroll para manter a navbar fixa estável e sem jank perceptível nas áreas autenticadas
|
||
|
||
**Checkpoint**: US5 fica estável visualmente nos breakpoints e temas suportados, com densidade e truncamento sob controle.
|
||
|
||
---
|
||
|
||
## Phase Final: Polish & Validação
|
||
|
||
**Purpose**: executar o guardrail mínimo e o checklist manual completo da feature antes do merge.
|
||
|
||
- [X] T024 Executar `npm run build` no diretório `frontend/` e corrigir qualquer erro de TypeScript ou compilação relacionado à navbar compartilhada
|
||
|
||
- [X] T025 [P] Executar os cenários de validação por persona, tema e breakpoint descritos em `specs/030-navbar-topo-ux/quickstart.md`, cobrindo visitante, cliente, admin e os breakpoints 320 px, 768 px, 1024 px e 1280 px
|
||
|
||
- [X] T026 [P] Fazer limpeza final em `frontend/src/components/Navbar.tsx` e `frontend/src/index.css`, removendo handlers, classes e estados legados substituídos pela refatoração de overlay único
|
||
|
||
---
|
||
|
||
## Dependencies & Execution Order
|
||
|
||
### Phase Dependencies
|
||
|
||
```text
|
||
Phase 1 (Setup)
|
||
│
|
||
└──→ Phase 2 (Foundational)
|
||
│
|
||
├──→ Phase 3 (US1 — Visitante)
|
||
├──→ Phase 4 (US2 — Cliente)
|
||
├──→ Phase 5 (US3 — Admin)
|
||
├──→ Phase 6 (US4 — Acessibilidade e estado)
|
||
└──→ Phase 7 (US5 — Responsividade premium)
|
||
│
|
||
└──→ Phase Final (Build + validação manual)
|
||
```
|
||
|
||
- **Phase 1**: sem dependências; prepara a configuração e os tokens visuais da navbar
|
||
- **Phase 2**: depende da conclusão de Phase 1; bloqueia todas as user stories
|
||
- **Phase 3 a Phase 7**: dependem de Phase 2; podem avançar em paralelo apenas quando não houver conflito de arquivo
|
||
- **Phase Final**: depende das user stories desejadas concluídas
|
||
|
||
### User Story Dependencies
|
||
|
||
- **US1 (P1)**: pode começar após Phase 2; independente de US2 e US3 no comportamento de perfil
|
||
- **US2 (P1)**: depende de Phase 2 e compartilha `Navbar.tsx` com US1, então a execução prática tende a ser sequencial no mesmo componente
|
||
- **US3 (P1)**: depende de Phase 2; pode ocorrer em paralelo apenas com T017, que toca `App.tsx`
|
||
- **US4 (P2)**: depende de T004 e T005 porque a base de overlay único e fechamento global precisa existir primeiro
|
||
- **US5 (P2)**: depende da estrutura renderizada por US1, US2 e US3 para calibrar responsividade final com dados reais
|
||
|
||
### Task-Level Notes
|
||
|
||
- T002 pode rodar em paralelo com T001
|
||
- T005 e T006 podem rodar em paralelo após T003 e T004
|
||
- T008 e T010 podem rodar em paralelo dentro de US1
|
||
- T012 pode rodar em paralelo com T011; T013 pode iniciar após T011
|
||
- T017 pode rodar em paralelo com T015 e T016
|
||
- T019 pode rodar em paralelo com T018; T020 depende da instrumentação criada em T018
|
||
- T022 pode rodar em paralelo com T021; T023 depende do ajuste de altura/layout consolidado
|
||
|
||
---
|
||
|
||
## Parallel Execution Examples
|
||
|
||
### User Story 1
|
||
|
||
```text
|
||
T007 → T009
|
||
T008 || T010
|
||
```
|
||
|
||
### User Story 2
|
||
|
||
```text
|
||
T011 → T013 → T014
|
||
T012 pode ocorrer em paralelo a T011
|
||
```
|
||
|
||
### User Story 3
|
||
|
||
```text
|
||
T015 → T016
|
||
T017 pode ocorrer em paralelo a T015
|
||
```
|
||
|
||
### User Story 4
|
||
|
||
```text
|
||
T018 → T020
|
||
T019 pode ocorrer em paralelo a T018
|
||
```
|
||
|
||
### User Story 5
|
||
|
||
```text
|
||
T021 → T023
|
||
T022 pode ocorrer em paralelo a T021
|
||
```
|
||
|
||
---
|
||
|
||
## Implementation Strategy
|
||
|
||
### MVP First
|
||
|
||
1. Concluir Phase 1 e Phase 2
|
||
2. Entregar US1 para visitante como primeiro incremento navegável
|
||
3. Adicionar US2 e US3 para fechar a matriz de perfis da navbar
|
||
4. Validar build e checklist manual antes de partir para polish visual fino
|
||
|
||
### Incremental Delivery
|
||
|
||
1. **Incremento 1**: Setup + Foundational
|
||
2. **Incremento 2**: US1 — navegação pública clara em desktop/mobile
|
||
3. **Incremento 3**: US2 + US3 — menus contextuais por perfil autenticado
|
||
4. **Incremento 4**: US4 — previsibilidade, teclado e ARIA
|
||
5. **Incremento 5**: US5 — acabamento responsivo premium
|
||
|
||
### Suggested MVP Scope
|
||
|
||
O menor recorte demonstrável é **US1** após a fase Foundational. O menor recorte funcional completo para a matriz de perfis é **US1 + US2 + US3**.
|
||
|
||
---
|
||
|
||
## Summary
|
||
|
||
| Fase | Tarefas | Escopo |
|
||
|------|---------|--------|
|
||
| Phase 1 | T001–T002 | Setup da navbar compartilhada |
|
||
| Phase 2 | T003–T006 | Estado e shell bloqueadores |
|
||
| Phase 3 | T007–T010 | US1 — visitante |
|
||
| Phase 4 | T011–T014 | US2 — cliente autenticado |
|
||
| Phase 5 | T015–T017 | US3 — admin |
|
||
| Phase 6 | T018–T020 | US4 — acessibilidade e previsibilidade |
|
||
| Phase 7 | T021–T023 | US5 — responsividade premium |
|
||
| Phase Final | T024–T026 | Build, validação manual e limpeza |
|
||
| **Total** | **26 tarefas** | **5 user stories + setup/foundational/polish** |
|
||
|