teqo-backup/docs/plans/largura-padrao-chat-sollinha-impl.md
2026-08-08 16:11:25 -03:00

84 lines
9.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Impl: B166 — Largura padrão do chat Sollinha com teto no desktop
Status: aprovado
Atualizado em: 2026-08-08
Issue: #414
Intenção: docs/plans/largura-padrao-chat-sollinha.md
Appetite restante: ~0,25–0,5 dia eng (mantido; sem migration)
## Leitura da intenção
- **Outcome:** no desktop de `/campanha`, o chat Sollinha abre — sozinho (carregamento) ou pelo botão do header — com `min(25% da janela, 360 px)` quando não há tamanho salvo; depois de aberto o resize é livre (sem teto superior, piso ~280 px mantido); o último tamanho escolhido pelo usuário é lembrado nas próximas aberturas; mobile (drawer full-screen) e demais superfícies intactos.
- **O que NÃO negociar:** teto de 360 px vale **só** para a abertura padrão (sem tamanho salvo); resize do usuário **sem máximo**; persistir **só o tamanho** (não as conversas); piso ~280 px; mobile drawer intacto.
- **O que reavaliar:** a “Direção no codebase” apontava `CampaignAISidebarShell.tsx` (Panel: `defaultSize="25"`, `minSize="280px"`, `maxSize="50"`, `collapsible`) — **confirmado como dono**. O mecanismo de persistência era aberto (“o executor escolhe”) — escolho persistência **própria em px** no `localStorage`, não `useDefaultLayout` do `react-resizable-panels` (razões abaixo).
## Abordagem recomendada
```mermaid
flowchart LR
A[CampaignAISidebarShell] -->|Group elementRef + onLayoutChanged isUserInteraction| B[save px → localStorage]
A -->|useIsMobile + resize(): PanelImperativeHandle| C[open size = saved ?? min 25%,360]
C --> D[remove maxSize=50 → resize livre]
B --> E[próxima abertura restaura px]
```
**Opções consideradas:** A | B | C | D
**Recomendação:** **A** — persistência própria em **px** + aplicação pontual no `useLayoutEffect`, porque casa com o aceite em unidades reais (px), persiste **apenas o tamanho** (hoje a abertura sozinha em `/campanha` é parte do comportamento — não se muda), e expressa o default `min(25%, 360 px)` sem depender de proporções do layout.
**Rejeitadas:**
- **B — `useDefaultLayout` do `react-resizable-panels`** (persistência de layout por %, `onlySaveAfterUserInteractions`): persiste o layout **inteiro, incluindo collapse/expand** → um usuário que fechou o chat o encontraria fechado no próximo load, o que muda o “abre sozinho ao carregar `/campanha`” que a intenção descreve como comportamento atual a preservar; além disso, o default `min(25%, 360)` exigiria medição do grupo de qualquer forma, e salvar % re-escala com a janela em vez de lembrar o tamanho em px escolhido.
- **C — teto via CSS (`max-width`/cap no Panel)**: travaria **também o resize do usuário** (produto diz “sem teto depois de aberto”) e briga com a matemática flex do library.
- **D — persistir % em vez de px**: drift com largura da janela; o aceite é explícito em px (“480–640 px hoje”, “teto de 360 px”, “o tamanho escolhido é lembrado”).
### Componentes / mudanças
- **`src/lib/sollinhaChatPanelWidth.ts`** (novo — puro, client-safe; referencia `campaignLastActedMunicipality.ts`): storage key `teoq:campaign:sollinha-chat-width-px`, leitura/escrita seguras (guard `typeof window`, try/catch private-mode), e a função pura `resolveChatPanelWidthPx(groupWidthPx, savedPx)` → `savedPx` válido (clampeado a `[CHAT_MIN_PX, groupWidthPx]`) **ou** `min(25% × groupWidth, 360 px)` (também clampeado). Move `CHAT_MIN_PX` (280) da shell para cá (fonte única; `minSize` do Panel e clamp do resolver passam a compartilhar).
- **`src/components/campaign/shell/ai/CampaignAISidebarShell.tsx`** (editar — dono do Group/Panel):
- Chat `Panel`: **remove `maxSize="50"`** (resize livre até o limite natural), mantém `minSize={CHAT_MIN_PX}`, `collapsible`, `collapsedSize={0}`, `defaultSize={CHAT_DEFAULT_PCT}` como valor inicial do library.
- `Group`: adiciona `elementRef` (medir largura do grupo) e `onLayoutChanged` — quando `meta.isUserInteraction` e o painel **não** estiver `isCollapsed()` e `inPixels >= CHAT_MIN_PX`, grava `Math.round(inPixels)` no storage.
- `useLayoutEffect` (client), gate por `useIsMobile()` + guardas: aplica `resolveChatPanelWidthPx(...)` via `panelRef.current.resize(px)` **uma vez** quando o painel está visível no desktop e **não** está colapsado e o usuário ainda **não** mexeu na sessão (ref `hasUserSized`). Re-executa só quando o eixo mobile→desktop cruza (load mobile-first cresce para desktop), para o default capado valer também aí.
- Separator/resize handle: intocado (já `md:flex`, existe).
- **Migration:** sem migration (zero schema).
- **Access / Consent:** nenhum (client-only; sem chave nova).
- **UI:** Impeccable **B** — encaixe no comportamento de abertura (sem redesign visual; o handle de resize já existe); shape→craft→critique→polish resumem-se a verificar o comportamento real em dev.
### Dados → forma (se aplicável)
- N/A — nenhum número novo apresentado; é ajuste de largura de painel.
## Fases verificáveis
1. **Tracer / server+schema:** nada de schema. Implementar `src/lib/sollinhaChatPanelWidth.ts` + unit spec (`tests/unit/sollinhaChatPanelWidth.unit.spec.ts`, espelhando `campaignLastActedMunicipality.unit.spec.ts`: leitura inválida/not-json, gravação, clear, e casos do `resolveChatPanelWidthPx` — grupo 1920 → default 360; grupo 1280 → 320; salvo 520 → 520 mesmo acima de 360; salvo longo clampeado ao grupo; salvo inválido → default).
2. **UI/wire:** editar `CampaignAISidebarShell.tsx` (remover `maxSize`, medir + aplicar, salvar em `onLayoutChanged`). Verificar em `pnpm dev` (porta 3266): abertura fresca em 1920 ≤360 px; arrastar para 520 px → reload restaura 520; fechar/reabrir mantém o da sessão; piso 280; mobile drawer intacto; painel colapsado (fechado pelo X) não reabre sozinho.
3. **Gates:** `pnpm gate:fast` na iteração; `pnpm push` na entrega. E2e `campaignMunicipalityResponsiveColumns` (condicional do `Fechar` no chat) deve continuar verde — comportamento de “abrir/colapsar muda colunas” inalterado (a largura default em 1600 px segue < 360 px). Avaliar se vale um e2e dedicado de persistência (barato em Playwright) — decidir na execução conforme appetite.
## Rabbit holes / Não escopo (engenharia)
- Persistir **conversas** do chat — corte explícito da intenção (sessão nova a cada abertura).
- Mexer no piso (~280 px) ou na semântica mobile drawer — fora de escopo.
- Usar `useDefaultLayout`/persistência de % do library — rejeitado (mudaria aberto/fechado e re-escalaria).
- Não criar hook intermediário pass-through; a lógica cabe no shell + lib puro (depth check: reusa `panelRef`/`useIsMobile` existentes).
## Riscos e mitigação
- **Semântica do `resize()`/`onLayoutChanged` do library (4.12.2):** `meta.isUserInteraction` discrimina drag de usuário vs imperativo (confirmado no bundle); `resize` valida/clampeia contra min/max. Mitigação: salvar só quando `!isCollapsed()` (arrastar até colapsar não grava 0); `isCollapsed()+hasUserSized` nas guardas para **nunca** forçar abrir nem sobrescrever escolha da sessão.
- **Cruzamento mobile↔desktop no meio da sessão:** efeito chaveado em `useIsMobile()`; `resize()` sobre painel `hidden` (mobile) é inerte, e as guardas evitam reabrir painel colapsado.
- **Garbage no storage:** parse/validação na leitura (espelha padrão `campaignLastActedMunicipality`/`recentVisits`), retorna default.
- **e2e existente:** largura default em viewport 1600 continua < 360 px (grupo ≈ 1320 px → 25% ≈ 330 px) → sem mudança de estágio de coluna.
## Aceite de engenharia
- [x] Aceite de produto da intenção ainda coberto (default capado + resize livre + persistência de tamanho; mobile intacto)
- [x] Invariantes AGENTS/engineering-standards (sem Local API/overrideAccess; client-only; identificadores em inglês)
- [x] Testes de domínio (unit do resolver/storage 12 casos; e2e dedicado cobre cap + drag livre + persistência via reload e via botão do header; responsive columns B158 segue verde)
## Revisão /simplify (3 reviewers) — desfecho
**Já resolvido na sessão (não reabrir):** assert racy do e2e (cap e reload agora usam `expect.poll` determinístico — o primeiro paint a 25% cru vazava o gate cru `>360`); double-click do Separator resetava para o default cru 25% sem teto → `disableDoubleClick`; `clamp` quando grupo < piso devolvia 280 > grupo → clamp padrão + casos unit; `boundingBox()!` do drag sem `toBeVisible` prévio; botão do header passou a ser coberto no e2e; `hasUserSizedRef`/`isCollapsed()`/guardas validados pelos 3 reviewers.
**Já resolvido por decisão (descartado de propósito):** `clearSavedChatWidthPx` sem caller de produção — mantido por simetria com os libs irmãos (`campaignLastActedMunicipality`/`recentVisits`) e usado pelo unit spec; `rAF` no primeiro commit em mobile resize de painel `display:none` — inerte, autocorrige no cruzamento de volta ao desktop.
**Explicitamente fora / defer com gatilho:**
- O sizing é um `requestAnimationFrame` one-shot; se um first-paint travado entregar `groupWidth <= 0`, o mount inteiro fica no default cru 25%. Gatilho para revisit: se um relato real (não o e2e) mostrar o painel abrindo > 360 px no desktop, trocar o one-shot por um `ResizeObserver` que aplica o tamanho ao estabilizar. Não registrado agora (sem evidência; rAF pós-layout mede 1664 no e2e).
- Floor de ~280 px no painel só é coberto no resolver unit, não contra `minSize`/drag real — comportamento pré-existente do library, fora do aceite deste item.