teqo-backup/docs/plans/sollinha-drawer-fecha-link-mobile-impl.md
Francisco Solla aa8fe582c0 feat(B198): drawer mobile do Sollinha fecha ao navegar por link interno
O renderer de links do chat decide interno vs externo (B187/B188); a decisão
pura de fechamento mora no owner src/lib/ai/markdownLinks.ts
(shouldCloseDrawerOnLinkClick: interno && mobile && clique simples) e o
markdownComponents estatico virou useMemo no corpo do CampaignAIChat para
alcancar o contexto. Desktop inalterado; links externos/modos de nova aba
mantem o drawer da aba de origem; sessao e restore intactos (close persiste
open:false).

- unit: 12 testes da decisao pura
- e2e (modo CI, E2E_PROD=1): interno fecha + navega sem load + reload nao
  reabre; externo abre popup e mantem o drawer
- debito B199/#672 (depends #660): race de persistencia ao fechar mid-stream
2026-08-11 14:29:29 -03:00

6.9 KiB

Impl: Sollinha mobile: fechar o drawer ao navegar por link

Status: aprovado Atualizado em: 2026-08-11 Issue: #660 Intenção: docs/plans/sollinha-drawer-fecha-link-mobile.md Appetite restante: herdado (~0,5 dia eng; um encaixe no renderer de links do chat)

Leitura da intenção

  • Outcome: em mobile, tocar num link interno (/campanha…) na resposta do Sollinha fecha o drawer no toque (antes de a página carregar) e a navegação segue no mesmo tab; reabrir restaura a conversa intacta; desktop inalterado; link externo (nova aba) não fecha o drawer da aba de origem; reload não reabre o drawer.
  • O que NÃO negociar: a conversa não pode ser descartada (sessão intacta); o painel desktop não pode fechar; só links das respostas do chat fecham (chips/sugestões/busca ficam fora — são sendMessage, não navegação, então nem chegam perto do renderer de links).
  • O que reavaliar: a hipótese "fechar é chamar setOpen(false) no toque, provavelmente só quando isMobile" — validar o efeito no userToggledOpenRef/openBy persistido (ver Riscos).

Decisões de engenharia

D1 — Onde fechar o drawer

Opções: A | B | C
Recomendação: A — no onClick do renderer de link interno (mobile) — porque é o
único ponto que conhece a tripla href + viewport + gesto do clique: o renderer
já decide interno vs externo (B187/B188), o `ctx.isMobile` vem do provider e o
click event diz se é clique simples (mesmo tab). Fecha no toque, exatamente o
aceite ("antes de a página carregar"). Sessão intocada.
Alternativas rejeitadas: B (efeito em pathname no provider) porque fecha em
QUALQUER navegação — incluindo back/forward e cliques na faixa de 10% da página
visível acima do drawer —, mais amplo que o aceite (o corte da intenção é "só
os links das respostas") e dispara após o commit da navegação, não no toque; C
(expor `closeForNavigation` no contexto que não marca intenção de usuário)
porque `requestOpen(false)` já é seguro (ver Riscos) — crescer o API do
contexto sem mudança de comportamento é over-engineering.

D2 — Onde mora a decisão pura (testável)

Opções: A | B
Recomendação: A — em `src/lib/ai/markdownLinks.ts` (dono da decisão de link
interno/externo, B187) — porque o regex `APP_INTERNAL_LINK` já é conhecimento
de link que vive no renderer; consolidar lá como `isCampaignInternalLink` e
adicionar `shouldCloseDrawerOnLinkClick` pura (href + isMobile + metadados do
click), unit-testável sem DOM. O renderer vira fiação fina.
Alternativas rejeitadas: B (deixar a condição inline no componente) porque a
regra de fechamento (mobile + interno + clique simples, ignorando
ctrl/meta/shift/alt/middle-click e defaultPrevented) merece pin de teste de
unidade, e o owner já existe.

D3 — Como o renderer alcança o contexto

markdownComponents hoje é constante de módulo (sem acesso ao useAISidebar). Mover para dentro de CampaignAIChat num useMemo (deps [ctx?.isMobile, ctx?.setOpen]) — o a interno ganha onClick que fecha quando a função pura responde true. setOpen (requestOpen) é estável via useCallback; o memo não re-renderiza o markdown à toa. Alternativa rejeitada: componente novo AssistantMarkdown — o chat já é o dono do markdown; fatiar em outro componente é cerimônia sem volatilidade.

Componentes / mudanças

  • isCampaignInternalLink (src/lib/ai/markdownLinks.ts): regex ^\/campanha(?:\/|$) promovido de CampaignAIChat.tsx para o owner; usado pelo renderer e pela função de fechamento. Sem mudança de semântica.
  • shouldCloseDrawerOnLinkClick(href, isMobile, event) (src/lib/ai/markdownLinks.ts): true ⇔ link interno && isMobile && clique simples (button === 0, sem ctrl/meta/shift/alt, !defaultPrevented). Modifier/middle-click abre em nova aba — a aba de origem mantém o drawer (mesma regra do link externo).
  • CampaignAIChat.tsx: markdownComponents vira useMemo no corpo do componente lendo ctx; o branch interno do a adiciona onClick que chama setOpen(false) quando shouldCloseDrawerOnLinkClick. Branch externo e desktop intactos (desktop: isMobile false → no-op).
  • tests/unit/aiMarkdownLinks.unit.spec.ts: pin das duas funções puras (interno/externo, viewport, modifiers, botão, defaultPrevented).
  • tests/e2e/campaignSollinhaContext.e2e.spec.ts: dois testes mobile com o mock de SSE já usado no arquivo (resposta com link interno → drawer fecha + URL muda sem load; resposta com link externo → drawer permanece e abre nova aba).
  • Migration: sem migration.
  • Access / Consent: N/A.
  • UI: Impeccable B — comportamento do drawer existente, sem superfície nova; shape→critique leve (não há shape novo).

Fases verificáveis

  1. Núcleo puro — markdownLinks.ts + unit tests; pnpm test:unit (spec de markdownLinks).
  2. Fiação UI — CampaignAIChat.tsx (useMemo + onClick); pnpm typecheck + pnpm lint.
  3. E2E — dois testes no campaignSollinhaContext.e2e.spec.ts; rodar só o arquivo.
  4. Gates — pnpm gate:fast, pnpm format:check, pnpm exec knip, pnpm check:cycles; push via pnpm push no PR.

Rabbit holes / Não escopo (engenharia)

  • Animar/transicionar o fechamento; mudar drawer/vaul; chips/sugestões/busca (não navegam); sessão/restauração; painel desktop; prefetch de link.
  • Decisão de "qual drawer state se anima durante navegação": não existe — setOpen(false) usa o mecanismo existente.

Riscos e mitigação

  • openBy persistido como 'user' após fechamento por navegação (porque requestOpen marca userToggledOpenRef): inerte — o restore só reabre quando session.open === true (CampaignAISidebarContext.tsx:89), e aqui open vira false antes do persist effect rodar (status ready + mudança de open). Reload não reabre (aceite). Validação no teste e2e existente "drawer aberto volta aberto após reload" não é afetada (aquele fluxo não navega).
  • Clique modificado (cmd/ctrl+click) em link interno: abre nova aba; sem fechar — a aba de origem mantém o chat montado. Coberto por unit test da função pura.
  • Clique em link durante frame de hidratação (isMobile não medido): impossível — o drawer só renderiza com isMobile true, que só vira true após a medição (useIsMobileMeasured).
  • markdownComponents recriado por render: o useMemo mantém identidade estável; ReactMarkdown recebe components novo apenas quando viewport/setOpen mudam.
  • Fechar + navegar no mesmo handler: state update (drawer) e router push (next/link) coexistem sem conflito; o e.defaultPrevented não é tocado.

Aceite de engenharia

  • Aceite de produto da intenção ainda coberto (5 itens do aceite → testes unit + e2e)
  • Invariantes AGENTS/engineering-standards (sem migration, sem access, identificadores em inglês, pt-BR só em strings de UI)
  • Testes de domínio previstos: unit (decisão pura) + e2e (comportamento drawer mobile)