# 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** |