sass-imobiliaria/specs/030-navbar-topo-ux/tasks.md

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.

• 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

• 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.

• 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

• 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

• 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

• 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.

• 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

• 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

• 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

• 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.

• 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

• 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

• 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

• 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.

• 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

• 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

• 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.

• 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

• 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

• 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.

• 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

• 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

• 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.

• T024 Executar npm run build no diretório frontend/ e corrigir qualquer erro de TypeScript ou compilação relacionado à navbar compartilhada

• 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

• 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

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

T007 → T009
T008 || T010

User Story 2

T011 → T013 → T014
T012 pode ocorrer em paralelo a T011

User Story 3

T015 → T016
T017 pode ocorrer em paralelo a T015

User Story 4

T018 → T020
T019 pode ocorrer em paralelo a T018

User Story 5

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