Compare commits

...

7 commits

Author SHA1 Message Date
Francisco Solla
1cc32a3d09 plano OPS78: Issue #784 2026-08-23 13:32:20 -03:00
Francisco Solla
1a377f51df plano OPS78: launch do worktree na variante max via gateway da Vercel 2026-08-23 13:32:20 -03:00
Francisco Solla
5ea288a88b docs(E1): changelog da extração do useAsyncSearchOptions 2026-08-23 13:16:47 -03:00
Francisco Solla
feb8e6cab8 docs(E1): triage de débitos aplicada — refs .spec.tsx residuais no impl plan 2026-08-23 13:16:47 -03:00
Francisco Solla
1c865bd822 refactor(campaign): E1 simplify — pin loading/retry/stale-quirk no spec e tipo local
Review estrutural + qualidade (sem P1): spec ganha 3 pins do contrato mais
sutil (loading em voo, retry pós-falha, quirk gate→not-ready com resposta
stale — comportamento herdado dos 3 originais, preservado); UseAsyncSearchOptionsResult
vira tipo local (export especulativo, knip types:error); docstring documenta
o quirk e o trim; plano registra o ajuste de execução.
2026-08-23 13:16:47 -03:00
Francisco Solla
9a66a23cf6 refactor(campaign): E1 extrai useAsyncSearchOptions (3ª cópia da busca com debounce)
DemandResponsibleMultiSelect (C143), ResponsibleMultiSelect (C90) e
AsyncSearchCombobox trocam o efeito duplicado (requestId/setTimeout 250ms/
loading/failed) pelo hook compartilhado src/hooks/useAsyncSearchOptions.ts,
com isQueryReady opcional preservando a semântica de query vazia de cada
consumidor. Comportamento preservado; unit novo do hook (renderHook +
fake timers); sem schema/server/migration.
2026-08-23 13:16:47 -03:00
Francisco Solla
e25e9e5607 plan(S12): âncora #novidades quebra no mobile — deep link não leva ao formulário 2026-08-23 12:50:07 -03:00
11 changed files with 517 additions and 115 deletions

View file

@ -4,6 +4,8 @@ Conteúdo movido do `AGENTS.md` em 2026-07-30 (fatiamento do paradigma de agente
---
**E1 — extração do hook compartilhado de busca assíncrona com debounce (2026-08-23):** a 3ª cópia do efeito de busca async (requestId + `setTimeout(250)` + loading/failed) — introduzida pela C143 em `DemandResponsibleMultiSelect` (demand), e presente em `ResponsibleMultiSelect` (C90) e `AsyncSearchCombobox` — vira o hook `useAsyncSearchOptions({ open, query, search, isQueryReady? }) → { options, loading, failed }` (`src/hooks/useAsyncSearchOptions.ts`, novo; constante `ASYNC_SEARCH_DEBOUNCE_MS` exportada). Os 3 componentes consomem o hook e mantêm só o que é seu (grupos por typeLabel, avatares, headings de sugestões do município, `pinnedOptions`, filtro de selecionados, mensagens de vazio); semântica de query vazia preservada por consumidor (Demand busca sempre → sugestões; ResponsibleMultiSelect reseta via `isContactSearchQueryReady`; combobox com gate configurável — o efeito sync `selected←value` fica no componente). Fix pontual: server actions intocadas (continuam props — hook client-safe por injeção), sem schema/migration/access/Consent. Testes: spec unit novo `tests/unit/useAsyncSearchOptions.unit.spec.ts` (renderHook + fake timers, 9 casos: debounce/trim, coalesce, gate reset, closed, failed + retry, in-flight loading, out-of-order, quirk gate→not-ready com resposta stale pinado — comportamento herdado dos 3 originais, registrado na decisão D3 do impl plan). Impl plan `docs/plans/extrair-hook-busca-assincrona-debounce-impl.md`. Verificação: unit 2428 + int 815 verdes, e2e activity/demand (campaignActivity, campaignRegisterDemand, campaignDemandVisibility) verdes em re-run (1 flake de cold-compile pré-existente isolado), tsc/lint/format/cycles/build verdes; knip com o erro de load pré-existente (exit 0); fora de escopo: `WizardMunicipalitySearchStep` (4ª variante, AbortController — defer com gatilho no plano).
**C142 — interface do /campanha respeita o perfil de permissão do assessor (2026-08-21):** a entrega fechada parte do C141 (que definiu os eixos `visibility`/`editing` no `campaignUser` e os gates server-side). Com o C142, a UI de todos os rascunhos staff do `/campanha` obedece de ponta a ponta o perfil de edição do assessor: com `editing = somente_leitura` não há nenhum controle de escrita em lugar nenhum (listas, detalhes, tabs, wizards); com `editing = tudo` o assessor enxerga/edita tudo o que vê; com `carteira` mantém o comportamento por carteira. Discriminação das entregas: (1) núcleo puro `src/lib/campaignAdvisorProfile.ts` com `advisorEditingScope()`/`rowEditingAllowed()` (retorna `none` para combinação incoerente `editing=tudo` + `visibility≠tudo`) e `gate: 'writable'` em `requireCampaignPageActor` (redireciona para `/campanha`); (2) todas as células compartilhadas (CampaignInlineEditableCell, MunicipalityRelationEditor, PhonesFieldEditor, DemandDescriptionEditor/Card/WorkflowCard, MunicipalityV2\*Cells, MunicipalityGoalAccountCard, ActivityTaskChecklist, SuggestionCard, MunicipalityPledgesPanel, etc.) ganharam o prop `readOnly`; (3) páginas staff — municípios (lista desktop+mobile, detalhe com tabs Overview/Updates/Leaderships/Suggestions, edição), pessoas (invite e criação gated), lideranças, dobradinhas, demandas, atividades, apoiadores, organizações — escondem os botões de criação (`Nova demanda`, `Nova atividade`, `Planejar giro`, `Novo`/`Importar CSV`, `Nova organização`, `Nova liderança`, `Nova dobradinha`) com `editingScope !== 'none'`; (4) home: `homeActionsForRole(role, editingScope)` filtra os 4 wizards para `somente_leitura` (sobra só o atalho de navegação); (5) `shouldMountQuickActionsFab` não monta o FAB para `somente_leitura`; (6) registry de quick actions (`resolveQuickActionsForPath`) recebe `editingScope` e filtra; (7) e2e novo `tests/e2e/campaignPermissionProfile.e2e.spec.ts` cobre os 3 perfis (somente_leitura sem controles, carteira com carteira, tudo com tudo) usando `createCampaignUser` com `visibility`/`editing`. Verificação: tsc/lint/format/knip/cycles/units (2419) + `gate:fast` verdes; PR em main com auto-merge (rebase); nada muda para coordinator/candidate/leader.
**S10 — Pixel do Meta (Facebook) na página pública de campanha (2026-08-19):** o time de campanha paga pode configurar o ID numérico do Pixel (Dataset do Events Manager) no admin — global `SiteSettings` → group "Rastreamento / Ads" → "ID do Pixel do Meta (Facebook)", mesma validação/normalização do precedente dos abaixo-assinados (5–20 dígitos, sem HTML/JS; regras agora vivem num único dono em `facebookPixel.ts`, com o `Petition` refatorado para o helper compartilhado). Com o ID configurado, a home pública de campanha (`/`) carrega o base code + `PageView` do Meta (injeção no layout do grupo `(home)` via `next/script`, escopada só à página de campanha — nada de PageView vazando para notícias/etc.); sem ID, nada é carregado (fail-closed). A conclusão da captura de novidades (S9) dispara exatamente um `Lead` (`content_name` "novidades-da-campanha", `eventID` UUID) no padrão do `PetitionForm` — nunca no page load. Leitura via `getCachedGlobal('site-settings')` (ISR sob a tag `global_site-settings`; a edição do admin já revalida a home). Migração `20260819_213947_add_site_settings_facebook_pixel_id` (colunas `tracking_facebook_pixel_id` + versão, sem backfill). Fora da fatia (gatilhos herdados do plano da petição): CAPI/Advanced Matching, dedup `eventID`, fila/retry de `Lead` e cookie banner/CMP. E2e novo `campaignHomePixel` (script `#meta-pixel-*` presente só com ID configurado, CDN stubada; `mode: serial` por precedente).

View file

@ -0,0 +1 @@
**E1 — extração do hook compartilhado de busca assíncrona com debounce (2026-08-23):** a 3ª cópia do efeito de busca async (requestId + `setTimeout(250)` + loading/failed) — introduzida pela C143 em `DemandResponsibleMultiSelect` (demand), e presente em `ResponsibleMultiSelect` (C90) e `AsyncSearchCombobox` — vira o hook `useAsyncSearchOptions({ open, query, search, isQueryReady? }) → { options, loading, failed }` (`src/hooks/useAsyncSearchOptions.ts`, novo; constante `ASYNC_SEARCH_DEBOUNCE_MS` exportada). Os 3 componentes consomem o hook e mantêm só o que é seu (grupos por typeLabel, avatares, headings de sugestões do município, `pinnedOptions`, filtro de selecionados, mensagens de vazio); semântica de query vazia preservada por consumidor (Demand busca sempre → sugestões; ResponsibleMultiSelect reseta via `isContactSearchQueryReady`; combobox com gate configurável — o efeito sync `selected←value` fica no componente). Fix pontual: server actions intocadas (continuam props — hook client-safe por injeção), sem schema/migration/access/Consent. Testes: spec unit novo `tests/unit/useAsyncSearchOptions.unit.spec.ts` (renderHook + fake timers, 9 casos: debounce/trim, coalesce, gate reset, closed, failed + retry, in-flight loading, out-of-order, quirk gate→not-ready com resposta stale pinado — comportamento herdado dos 3 originais, registrado na decisão D3 do impl plan). Impl plan `docs/plans/extrair-hook-busca-assincrona-debounce-impl.md`. Verificação: unit 2428 + int 815 verdes, e2e activity/demand (campaignActivity, campaignRegisterDemand, campaignDemandVisibility) verdes em re-run (1 flake de cold-compile pré-existente isolado), tsc/lint/format/cycles/build verdes; knip com o erro de load pré-existente (exit 0); fora de escopo: `WizardMunicipalitySearchStep` (4ª variante, AbortController — defer com gatilho no plano).

View file

@ -0,0 +1,74 @@
# Âncora #novidades quebra no mobile — deep link não leva ao formulário
Status: registrado
Atualizado em: 2026-08-23
Issue: #780
Priority: P1
Impeccable: A — N/A (correção funcional de scroll; sem mudança visual)
Rascunho UI: N/A — sem UI
Appetite: ~0,5–1 dia eng; um outcome verificável (deep link + CTA levam ao formulário no mobile e no desktop)
Responsável: —
## Intenção
O link `jorgesolla1313.com.br/#novidades` deveria levar o visitante direto ao formulário de captura de novidades da home de campanha. No desktop ele funciona; no celular não — a página abre no topo e o usuário não é levado ao formulário. Esse link será usado para direcionar tráfego (orgânico/pago/WhatsApp) direto para a captura, na janela eleitoral (1º turno 04/10). Cada visita que não chega ao formulário é audiência perdida. Precisamos garantir que o mesmo link leve ao formulário nos dois: desktop e mobile.
## Persona e fluxo
- **Persona / contexto:** visitante da home de campanha que chega pelo link `/#novidades` (vindo de WhatsApp, anúncio, material de campanha) ou clicando no CTA "Receba novidades" do hero — no celular ou no desktop.
- **Job principal:** ao abrir o link (ou clicar no CTA), ser levado direto à seção do formulário de captura, sem rolar manualmente.
- **Fluxo desejado:**
1. Abre `jorgesolla1313.com.br/#novidades` (ou clica no CTA do hero).
2. A página rola até a seção "Receba as novidades da campanha" com o formulário visível.
3. Preenche nome + WhatsApp e envia (fluxo S9 já existente).
- **Anti-goals de produto:** mudar o layout/visual da home; mexer no modelo de scroll de outras rotas; criar mecanismo paralelo de navegação; alterar o fluxo do formulário S9.
### Esboço de fluxo (A — sem UI)
<!-- Omitido: classe A, sem mudança visual. O fluxo é o mesmo do S9; só a chegada ao formulário passa a funcionar no mobile. -->
## Objetivo e aceite
- Abrir `jorgesolla1313.com.br/#novidades` no celular leva à seção do formulário (não fica no topo).
- Clicar no CTA "Receba novidades" do hero no mobile rola até a seção do formulário.
- O comportamento no desktop continua funcionando (sem regressão).
- Respeita `prefers-reduced-motion` (sem scroll suave forçado quando o usuário prefere menos movimento).
## Dados (intenção)
- **Vou apresentar dados?** Não — N/A. Correção de navegação/scroll, sem métrica ou dado novo.
## Direção no codebase (hipótese)
- **Áreas prováveis:** `src/app/(frontend)/(home)/layout.tsx` (container de scroll interno), `src/components/CampaignHero.tsx` (CTA `#novidades`), `src/app/(frontend)/(home)/CampaignNewsletterSection.tsx` (`id="novidades"`), um novo componente cliente de scroll por hash na home.
- **Precedente a olhar:** `captura-novidades-home-campanha.md` (S9, Issue #93 — entrega-pai); `CampaignStorySection.tsx` usa `scrollIntoView` (padrão de scroll programático já existente).
- **Risco de acoplamento:** a home é dona do container de scroll interno (`h-dvh overflow-y-auto`) porque o `body` está `overflow-hidden` — a correção deve atuar nesse modelo sem quebrar o scroll de outras rotas públicas.
## Dependências
- Nenhuma dura. Soft: S9 (formulário e seção já entregues).
## Fora de escopo
- Corrigir o mesmo padrão de âncora em outras rotas públicas (`[type]`, `artigos`) — mesmo modelo de container, mas sem pedido; registrar gatilho se reaparecer.
- Mudar o modelo de scroll global (tirar `overflow-hidden` do body) — decisão de arquitetura maior, fora do appetite.
## Rabbit holes de produto
- **"Aproveita e arruma as âncoras de todas as rotas públicas."** Escopo explode para o modelo de scroll inteiro do site. **Corte neste item:** só a home de campanha e o `#novidades`.
- **"E se o formulário tiver um id próprio?"** O `#novidades` já aponta para a seção que contém o formulário; criar id extra no formulário é mudança de contrato de URL sem pedido. **Corte:** manter `#novidades`.
## Questões em aberto (produto)
- **Garantir que o deep link caia exatamente no formulário, não só no topo da seção?** **Opções:** A) rolar até a seção `#novidades` (o formulário fica logo abaixo do título — suficiente) | B) rolar até o próprio formulário. **Recomendação:** A — a seção é o contrato de URL já publicado; o formulário fica visível na mesma tela. _(assumido — validar com produto)_
## Referências
- GitHub Issue #780
- Rascunho UI (gate): N/A
- `src/app/(frontend)/(home)/layout.tsx` — container de scroll interno
- `src/components/CampaignHero.tsx` — CTA `href="#novidades"`
- `src/app/(frontend)/(home)/CampaignNewsletterSection.tsx` — `id="novidades"`
- `tests/e2e/campaignNewsletter.e2e.spec.ts` — cobre o CTA no viewport desktop; falta cobertura mobile
- `docs/plans/captura-novidades-home-campanha.md` (S9, Issue #93)
- `AGENTS-public.md` — convenções do site público

View file

@ -0,0 +1,113 @@
# Impl: Extrair hook compartilhado de busca assíncrona com debounce (3ª cópia)
Status: rascunho
Atualizado em: 2026-08-23
Issue: #765
Intenção: body é spec (E1 — não há link de plano; a spec é a própria intenção citada)
Appetite restante: fix pontual P2 — sem appetite declarado no body; tratado como fix pontual (refactor estrutural sem schema/server/migration)
## Leitura da intenção
- **Outcome:** a 3ª cópia do efeito de busca assíncrona com debounce (requestId + `setTimeout` 250ms + loading/failed) desaparece: um hook compartilhado `useAsyncSearchOptions({ open, query, search }) → { options, loading, failed }` é consumido por `DemandResponsibleMultiSelect` (C143), `ResponsibleMultiSelect` (C90) e `AsyncSearchCombobox`; cada componente mantém só o que é seu (grupos, avatar, sugestões, caps).
- **O que NÃO negociar:** comportamento idêntico nos 3 call sites (fix pontual — nenhuma mudança de UX); a semântica de query vazia **difere** entre os 3 e o hook não pode unificá-la; padrão `searchRef`/`isQueryReadyRef` preservado; server actions intocadas (continuam como props); `WizardMunicipalitySearchStep` (4ª variante, AbortController/requestSeq) fica fora; copy pt-BR e identificadores em inglês.
- **O que reavaliar:** a intenção propõe `T extends { id: string }` — **errado contra o código**: os três tipos reais (`RelationOption`, `ResponsibleOption`, `AsyncSearchOption`) usam `id: number` (D2). A intenção não fixa onde o hook mora — a exploração mostra que `src/hooks/` tem só `use-mobile.ts` (viewport), hooks de campanha hoje colacam no domínio (`useMicTranscript` em `shell/ai/`, `useHomeSearchQuery` em `dashboard/`) e `src/lib/campaignLongPress.ts` já hospeda um hook; a fronteira é deliberada em D1.
## Abordagem recomendada
```mermaid
flowchart LR
subgraph hook["src/hooks/useAsyncSearchOptions.ts (novo — folha, client-safe)"]
H["useAsyncSearchOptions<T extends { id: number }>({ open, query, search, isQueryReady? })"]
OUT["{ options: T[]; loading: boolean; failed: boolean }"]
H --> OUT
end
H --> C1["DemandResponsibleMultiSelect — sem gate (query vazia busca; server devolve sugestões do município)"]
H --> C2["ResponsibleMultiSelect — isQueryReady={isContactSearchQueryReady} (reset quando não-pronta)"]
H --> C3["AsyncSearchCombobox — isQueryReady configurável (a prop segue no componente p/ render do vazio)"]
```
**Opções consideradas:** D1–D5 abaixo (fronteira de módulo, API/generics, gate, fronteira hook×componente, exports/teste).
**Recomendação:** novo módulo `src/hooks/useAsyncSearchOptions.ts` exportando `useAsyncSearchOptions<T extends { id: number }>` + `ASYNC_SEARCH_DEBOUNCE_MS` (250) + o tipo do resultado; os 3 componentes trocam o efeito duplicado por uma chamada ao hook, passando `search` (server action já recebida por prop — o hook fica client-safe por injeção) e, onde existem, seus gates (`isContactSearchQueryReady` no `ResponsibleMultiSelect`, gate configurável no `AsyncSearchCombobox`, nenhum no `DemandResponsibleMultiSelect`). Teste unitário do hook com `renderHook` + fake timers (padrão `campaignHomeSearchQuery.unit.spec.ts`). Nada de schema/server/access/Consent; sem migration.
**Rejeitadas:** ver D1–D5.
### Decisões de engenharia
**D1 — Onde mora o hook (fronteira de módulo; caro de reverter).**
Opções: A) `src/hooks/useAsyncSearchOptions.ts` (novo, junto a `use-mobile.ts`) | B) `src/lib/useAsyncSearchOptions.ts` | C) `src/components/campaign/shared/useAsyncSearchOptions.ts`.
Recomendação: **A** — (1) `src/hooks/` é o home designado de hooks React do repo e **não é pinado**: o pin de top-level de `codebaseConventions.unit.spec.ts` (L389) cobre só `src/utilities/` — um módulo novo em `src/hooks/` não exige registro nem atualização de spec; (2) direção de dependência: `src/hooks/` é folha do DAG (importa só `react`), importável de `components/` sem ciclo (madge confirma) — a cadeia `lib/ → utilities/ → components/ → app/` não é violada; (3) o hook é deliberadamente genérico (não conhece vocabulário de campanha: `T` e gate são injetados), então uma localização em path de campanha superestimaria a posse do domínio; (4) sem diretiva `'use client'` (módulo client-safe folha consumido só por client components, como `use-mobile.ts`).
Alternativas rejeitadas: B — o único hook em `lib/` (`useCampaignLongPress` em `campaignLongPress.ts`) está colocado ali por coesão de módulo (hook + constante `CAMPAIGN_LONG_PRESS_MS` + handlers próprios no mesmo arquivo); `useAsyncSearchOptions` não tem lógica lib-side para colocar junto (`isContactSearchQueryReady` fica no módulo lib existente, injetado como prop — depth check), então em `lib/` o hook alargaria a exceção "React em lib" sem payoff de coesão e borraria "lib = helpers puros" para leitores futuros; C — os precedentes de colação (`useMicTranscript`, `useHomeSearchQuery`) são hooks **privados de feature** com estado acoplado à feature; este hook atravessa `demand/` + `shared/` e sua API não referencia tipos de campanha, e `shared/` comunica "componente compartilhado de campanha" — localização enganosa para um consumidor genérico futuro.
**D2 — API do hook e debounce.**
Opções: A) `T extends { id: string }` (como sugerido na intenção) | B) `T extends { id: number }` | C) `T` sem constraint | D) debounce como prop opcional com default 250.
Recomendação: **B + debounce fixo** — os três call sites reais têm `id: number` (`RelationOption`, `ResponsibleOption`, `AsyncSearchOption`); a constraint documenta o shape e rejeita consumidor divergente sem custo (o hook não inspeciona `id` — filtragem fica nos componentes). Debounce fixo: os 3 usam 250ms hoje; prop é especulação (YAGNI). A constante é **exportada** (`ASYNC_SEARCH_DEBOUNCE_MS`), espelhando os precedentes do repo (`HOME_SEARCH_DEBOUNCE_MS` em `campaignHomeSearchContract.ts`, `CAMPAIGN_LONG_PRESS_MS` em `campaignLongPress.ts`) — é o que permite o teste com fake timers sem hardcode.
Alternativas rejeitadas: A — nenhum call site usa `id: string`; constraint errada contra o código; C — perde a documentação do shape mínimo e permite uso divergente; D — barato de adicionar depois (gatilho: 4º consumidor com debounce ≠ 250ms); não decidir agora é a decisão.
**D3 — Gate de query mínima (muda API pública do hook — registrar).**
Opções: A) prop opcional `isQueryReady?: (query: string) => boolean`, default `() => true`, lida via ref (padrão `isQueryReadyRef` preservado) e checada **dentro do efeito, antes do timeout**, com reset `options/loading/failed` quando false | B) hook sempre busca; gate fica fora (cada componente pré-filtra) | C) unificar: o hook aplica `isContactSearchQueryReady` por default.
Recomendação: **A** — reproduz borda a borda os 3 comportamentos: `DemandResponsibleMultiSelect` busca sempre (default `() => true`; query vazia → server devolve sugestões de assessores do município — fill-in C143), `ResponsibleMultiSelect` reseta com `isContactSearchQueryReady` (L80-85), `AsyncSearchCombobox` com gate configurável (`DemandFields` município, `ContactCombobox` contato). O reset in-effect (options=[], loading=false, failed=false) é o mesmo código nos 2 gated e mora no hook; o guard `requestId` em then/catch/finally e o `cleanup` `clearTimeout` também. Trim: o hook aplica `query.trim()` internamente (os 3 trimmam hoje); server actions seguem trimmando defensivamente — intocadas. **Quirk preservado (pós-`/simplify` pinado por teste):** o branch de gate não-pronto **não invalida** o requestId em voo — herdado fielmente dos 3 originais, uma resposta stale ainda aterrissa depois do reset; o teste `stale in-flight response lands after the query turns not-ready` pinça o comportamento atual (defer com gatilho: um consumidor que exija invalidação real).
Alternativas rejeitadas: B — o reset + guard vazaria para cada componente, recriando a duplicação que a entrega elimina; C — unificar mudaria comportamento (Demand ganharia um gate que não tem hoje) e a intenção é explícita: "a semântica de query vazia difere e o hook não pode unificá-la".
**D4 — Fronteira hook × componente (o que fica em cada um).**
Opções: A) hook devolve só `{ options, loading, failed }` brutos; todo filtro/agrupamento/headings/caps fica no componente | B) hook também filtra selecionados (recebe `selected`) | C) hook devolve estado normalizado (grupos prontos).
Recomendação: **A** — a filtragem difere entre os 3 (`Set<number>` de ids no Demand vs chave `relationTo:id` no Responsible vs `id !== selected?.id` no combobox), grupos por `typeLabel` só existem no Responsible, `pinnedOptions`/grupos fixos "Seleção"/"Selecionado"/"Resultados" só no combobox, `shortQuery`/headings "Sugestões do município"/"Assessores" e avatares só no Demand — nenhum conhecimento é comum; passar isso ao hook criaria API especulativa e pass-through (depth check: não criar).
Alternativas rejeitadas: B — unificar a chave de filtro mudaria a semântica de dedupe do `ResponsibleMultiSelect` (`relationTo:id`); C — normalizar 3 formas distintas numa só é a duplicação inversa (o hook conheceria UI de 3 consumidores).
**D5 — Exports do módulo, "registro" e teste unitário.**
Opções: A) módulo exporta o hook + `ASYNC_SEARCH_DEBOUNCE_MS` + tipo `UseAsyncSearchOptionsResult<T>`; teste unitário novo com `renderHook` + `vi.useFakeTimers` | B) sem tipo de retorno exportado; cobertura só pelos specs existentes dos consumidores.
Recomendação: **A (execução ajustada pós-`/simplify`)** — "registrar o hook com type `useAsyncSearchOptions`" aqui significa exportar o hook com sua assinatura tipada (parâmetros `{ open, query, search, isQueryReady? }` + retorno `{ options: T[]; loading: boolean; failed: boolean }`) — **não há pin/registro a atualizar**: `src/hooks/` não é pinado (o pin de `codebaseConventions.unit.spec.ts:389` cobre só top-level de `src/utilities/`), knip valida o export consumido, e hook não é componente Payload (sem import map). **Ajuste:** o tipo `UseAsyncSearchOptionsResult<T>` ficou **local (não exportado)** — o revisor de qualidade apontou export especulativo com zero consumidores e o knip local (regra `types: error`) flagearia; a anotação de retorno interna o mantém como contrato documentado. Teste: `tests/unit/useAsyncSearchOptions.unit.spec.ts` (`.ts`, não `.tsx` — `renderHook` não exige JSX) no padrão de `campaignHomeSearchQuery.unit.spec.ts` (`renderHook` + `vi.useFakeTimers` + `vi.advanceTimersByTime(ASYNC_SEARCH_DEBOUNCE_MS)`) — infra já existente (também `useMicTranscript`, `campaignCellAutosave`), **sem infra nova**. Como a `search` é injetada por prop (e não importada de módulo), o teste passa `vi.fn()` com resolves/rejects controlados — não há módulo server a mockar; o padrão de mock de `activityOverlay.unit.spec.tsx` (L20-23) continua valendo para os consumidores, que ficam intocados. Pós-`/simplify` o spec ganhou 3 casos pin (contratos mais sutis do hook): `loading === true` em voo, retry pós-falha, e o quirk gate→not-ready com resposta stale em voo (ver D3).
Alternativas rejeitadas: B — a mecânica requestId/gate/debounce é a parte mais sutil da extração (fonte de regressão silenciosa) e hoje só é coberta indiretamente por e2e; o teste direto do hook é barato e pinaria o contrato que os 3 componentes passarão a compartilhar.
### Componentes / mudanças
- **`useAsyncSearchOptions` + `ASYNC_SEARCH_DEBOUNCE_MS`** (`src/hooks/useAsyncSearchOptions.ts`, novo; tipo de retorno `UseAsyncSearchOptionsResult<T>` **local**, não exportado — knip `types: error`): estado `options/loading/failed`; refs `requestId`, `searchRef`, `isQueryReadyRef` (atribuídos no render, como hoje); efeito com `if (!open) return`; gate lido via ref **antes** do timeout (reset e return); `setTimeout(ASYNC_SEARCH_DEBOUNCE_MS)` → `setLoading(true)/setFailed(false)` → `search(query.trim())` com guards `requestId.current !== currentRequestId` em then/catch/finally; cleanup `clearTimeout`. Sem diretiva `'use client'` (folha client-safe, como `use-mobile.ts`). Deps do efeito: `[open, query]` — gate e search via ref, sem re-execução por identidade (padrão preservado).
- **`DemandResponsibleMultiSelect`** (`src/components/campaign/demand/DemandResponsibleMultiSelect.tsx`): remove estados/refs L61-69 e o efeito L71-94; `const { options, loading, failed } = useAsyncSearchOptions({ open, query, search })` (sem gate — busca sempre). Mantém: `selected`/chips/avatar/`(criador)`/`lockCreator`/hidden inputs, `visibleOptions` (filtro por `selectedIds`), `shortQuery` e headings "Sugestões do município"/"Assessores", mensagens de vazio.
- **`ResponsibleMultiSelect`** (`src/components/campaign/shared/ResponsibleMultiSelect.tsx`): remove L67-76 e o efeito L78-107; hook com `isQueryReady={isContactSearchQueryReady}`. Mantém: `groups` por `typeLabel`, `atCapacity`, mensagem "Digite ao menos dois caracteres…" (o import de `isContactSearchQueryReady` permanece — usado no render, L224), hidden JSON, chips com `typeLabel`.
- **`AsyncSearchCombobox`** (`src/components/campaign/shared/AsyncSearchCombobox.tsx`): remove estados/refs L49-60 e o efeito de busca L66-95; hook com `isQueryReady` (a prop continua no componente — usada no render do vazio, L189). **O efeito sync `selected←value` (L62-64) FICA no componente** (é contrato do combobox, não da busca). Mantém: `pinnedOptions`/`pinnedGroupHeading`, grupos "Seleção"/"Selecionado"/"Resultados", `choose()`, `emptyOptionLabel`, `queryTooShortMessage`.
- **Consumers de `AsyncSearchCombobox`** (`DemandFields.tsx:85`, `ContactCombobox.tsx:38`, `ActivityTaskFields.tsx:98`): intocados (o gate é resolvido dentro do combobox).
- **`tests/unit/useAsyncSearchOptions.unit.spec.ts`** (novo): ~5 `it` — debounce só dispara após `ASYNC_SEARCH_DEBOUNCE_MS`; query rápida em sequência cancela o timer anterior (só a última busca); gate não-pronto → reset sem chamar `search`; resposta fora de ordem descartada (requestId) e `catch` → `failed`, `finally` → `loading=false`; `open=false` não busca.
- **Migration:** nenhuma (refactor client, sem schema). **Access / Consent:** nenhum (server actions intocadas; sem escrita nova, PII ou chave). **UI:** Impeccable A — refactor estrutural sem superfície nova.
### Dados → forma
N/A — refactor de estado de UI; nenhuma métrica, série, ranking ou mapa novo.
## Fases verificáveis
1. **Tracer / schema+server** — nada de schema/server (as server actions já são props dos 3 componentes e ficam intocadas; sem migration; sem access/Consent). O tracer é o próprio hook: criar `src/hooks/useAsyncSearchOptions.ts` + `tests/unit/useAsyncSearchOptions.unit.spec.ts` e rodar `pnpm gate:fast` — a mecânica requestId/debounce/gate fica provada isolada (renderHook + fake timers) antes de tocar os 3 componentes.
2. **UI** — migrar os 3 componentes (ordem: `AsyncSearchCombobox` e `ResponsibleMultiSelect` em `shared/` primeiro, depois `DemandResponsibleMultiSelect` em `demand/`), mantendo em cada um só o que é seu (D4); registrar o hook com seu type público `useAsyncSearchOptions` (assinatura + `UseAsyncSearchOptionsResult<T>` exportados — sem pin a atualizar: `src/hooks/` não é pinado; knip valida o consumo). Rodar os e2e afetados da superfície antes do push: `pnpm test:e2e:affected` (activity + demand).
3. **Gates** — `pnpm gate:fast`; `pnpm check:cycles` (hook é folha — sem ciclo), `pnpm format:check`, `pnpm exec knip`, `pnpm test` (unit + int — incl. `campaignDemandWorkflow.int.spec.ts`, que cobre o record de responsáveis C143), `pnpm build`; push via `pnpm push`.
## Rabbit holes / Não escopo (engenharia)
- `WizardMunicipalitySearchStep.tsx:107-139` (4ª variante: POST + `AbortController` + `requestSeq`) — mecânica diferente; fora, como a intenção marca.
- `useHomeSearchQuery` (`src/components/campaign/dashboard/useHomeSearchQuery.ts`) — debounce-only, sem requestId/loading/failed e com contrato de busca própria (`HOME_SEARCH_DEBOUNCE_MS` em lib); não é a mesma mecânica; sem gatilho para consolidar (1 variante).
- Adicionar `AbortController` ao hook — os 3 hoje são guardados por requestId com cleanup só `clearTimeout`; abort mudaria o comportamento sob requisições lentas (o requestId descarta a resposta, não cancela o fetch). Defer com gatilho: call site que exija cancelamento real de rede.
- Prop `debounceMs` — especulação (D2); gatilho: 4º consumidor com debounce ≠ 250ms.
- Unificar a semântica de query vazia / normalizar grupos, pinned, headings ou avatares no hook — D3/D4.
- Mexer nos specs existentes que mockam as server actions (`activityOverlay.unit.spec.tsx`, `activityAgendaInteractions.unit.spec.tsx` mockam `searchActivityResponsibleOptionsAction` na camada de componente) — continuam válidos; a action não muda.
- DRY <3 call sites não é rabbit hole aqui — são exatamente 3 call sites reais com comportamentos divergentes (gate/sugestões/grupos), por isso o hook é fino e o resto fica nos componentes.
## Riscos e mitigação
- **Regressão silenciosa de comportamento em 3 superfícies:** mitigado por (a) equivalência borda-a-borda no diff (open/gate/trim/debounce/requestId em then/catch/finally/cleanup — cada linha do efeito removido tem correspondente no hook), (b) teste unitário do hook com fake timers e resolves controlados (inclui fora-de-ordem), (c) e2e afetados: `campaignActivity.e2e.spec.ts`, `campaignRegisterDemand.e2e.spec.ts`, `campaignDemandVisibility.e2e.spec.ts` + `tests/int/campaignDemandWorkflow.int.spec.ts` (C143).
- **Gate mal copiado (reset fora do efeito):** o reset de `options/loading/failed` quando `isQueryReady` é false é parte da semântica de hoje (ResponsibleMultiSelect L80-85, AsyncSearchCombobox L68-73) — o hook o reproduz dentro do efeito, antes do timeout; teste cobre o caso.
- **`requestId` off-by-one:** padrão idêntico ao atual (`++requestId.current` capturado, comparado em then/catch/finally); teste de resposta fora de ordem pinça.
- **Ciclo de import:** hook importa só `react`; `check:cycles` confirma a folha do DAG.
- **knip:** exports do hook consumidos pelos 3 componentes; `ASYNC_SEARCH_DEBOUNCE_MS` usado no spec — nenhum export órfão.
## Aceite de engenharia
- [ ] Aceite de produto da intenção ainda coberto: 3ª cópia eliminada; os três componentes consomem `useAsyncSearchOptions`; comportamento idêntico (debounce 250ms, requestId, loading/failed, gates por componente); cada um mantém grupos/avatar/sugestões/caps
- [ ] Invariantes AGENTS/engineering-standards: hook client-safe por injeção (server actions continuam props — sem import server no hook); sem migration; sem access/Consent; identificadores em inglês; copy pt-BR intocada
- [ ] Testes de domínio previstos: unit novo do hook (`renderHook` + fake timers) — access/write paths não mudam (server actions intocadas), então sem testes int novos; e2e afetados da superfície activity/demand rodados
- [ ] Self-score decision-quality: 5/5 (abaixo)
## Self-score decision-quality: 5/5
1. **Decisões caras têm rejeitadas?** Sim — D1 (fronteira de módulo, caro) e D3 (API pública do hook com gate) têm opções e rejeitadas explícitas; D2/D4/D5 são baratas mas registradas porque a intenção exigiu deliberar a API (generics, debounce, fronteira hook×componente, teste).
2. **Abordagem cabe no appetite?** Sim — fix pontual P2: refactor estrutural que **remove** ~90 linhas de efeito duplicado, sem schema/server/migration/UI nova; nada de AbortController, `debounceMs`, normalização ou unificação de gates.
3. **Rabbit holes nomeados?** Sim — `WizardMunicipalitySearchStep`, `useHomeSearchQuery`, AbortController, `debounceMs`, unificação de query vazia/grupos, specs existentes que mockam as actions.
4. **Depth check: reusa shells/helpers existentes?** Sim — reusa `isContactSearchQueryReady` (lib existente) como gate injetado (sem duplicar a lógica de query mínima); preserva os padrões `searchRef`/`isQueryReadyRef`; exporta a constante de debounce como os precedentes `HOME_SEARCH_DEBOUNCE_MS`/`CAMPAIGN_LONG_PRESS_MS`; sem pass-through (D4).
5. **Intenção permanece satisfeita?** Sim — o hook extraído tem exatamente o shape da intenção `({ open, query, search }) → { options, loading, failed }` (com `isQueryReady` opcional para os gates existentes); os três consumidores o usam; comportamento preservado e coberto por unit + e2e — a engenharia não reescreveu o outcome.

View file

@ -0,0 +1,62 @@
# Default de launch do worktree opencode passa a usar o DeepSeek na variante max servido pelo gateway da Vercel
Status: rascunho
Atualizado em: 2026-08-23
Issue: #784
Priority: P2
Impeccable: A — N/A sem UI
Rascunho UI: N/A — sem UI
Appetite: ~0,5–1 dia eng; um outcome verificável
Responsável: —
## Intenção
Hoje `pnpm worktree next/plan/new` terminam abrindo o opencode com o DeepSeek no modo default, servido direto pelo provedor de inferência mais barato. A política mudou: a sessão que abre nesses lançamentos deve usar a variante de raciocínio mais forte (max) do DeepSeek, servida pelo gateway de IA da Vercel — rota com cache, estabilidade e failover, em vez da rota direta atual. Trocar o default é editar a constante do preset (o próprio mecanismo OPS26 diz "trocar de modelo é editar a constante"), mas hoje o repo não expõe a variante max nem o provider do gateway — este item expõe os dois e só isso. Não queremos mudar o cardápio de modelos de execução de Issues, nem a config de máquina do humano.
## Persona e fluxo
- **Persona / contexto:** dev que lança worktrees de planejamento/execução e cai direto numa sessão opencode com a tarefa pela frente.
- **Job principal:** abrir a sessão do worktree já no modelo de raciocínio mais forte, sem nenhuma ação manual.
- **Fluxo desejado:** rodar `pnpm worktree next/plan/new` → a sessão abre com a variante max servida pelo gateway → trabalho começa.
- **Anti-goals de produto:** não trocar o modelo de execução de Issues (work-issue); não tocar no `~/.config/opencode/opencode.jsonc` do humano; não virar item de infra/credencial do gateway em si.
## Objetivo e aceite
- Ao rodar cada um dos três comandos de launch, a sessão abre com a variante max via gateway — verificável pela linha de launch emitida pelo preset e pelos testes unitários atualizados.
- Guardrails: nenhuma mudança no fluxo de execução de Issues; config global do humano intocada; docs históricos congelados.
## Dados (intenção)
Dados: N/A — item de tooling/launch, sem superfície de dados.
## Direção no codebase (hipótese)
- **Áreas prováveis:** `scripts/lib/worktree.mjs:23` (constante do preset, emitida em `:143`); testes `tests/unit/worktree.unit.spec.ts:151-197` e `tests/unit/opencodeCommands.unit.spec.ts:37`; repo `opencode.json` (adicionar provider OpenAI-compatible do gateway e expor a variante max); textos de doc `.agents/shell/worktree.sh:10`, `scripts/worktree.mjs:27,778`, `.agents/skills/worktree-next-issue/SKILL.md:34`.
- **Precedente a olhar:** OPS26 (criou o preset e o mecanismo "trocar modelo = editar a constante"), OPS31/OPS25 (extensões do launch).
- **Risco de acoplamento:** baixo — a constante é single source e os testes a seguram; qualquer mudança de string quebra testes, o que é a verificação do item.
## Dependências
- Nenhuma dura. Soft: provider do gateway disponível/validável no ambiente de dev local para o executor confirmar a rota.
## Fora de escopo
- Config global `~/.config/opencode/opencode.jsonc` do humano — fica de fora por decisão de produto.
- Cardápio de modelos de execução de Issues (work-issue/plan-issue como comandos de trabalho) — não muda.
- Documentos históricos (`docs/plans`, `docs/CHANGELOG-AGENTS.md`) — congelados, não editar.
- Infra/credenciais do gateway — o repo só expõe o provider; chaves/endpoint continuam fora do repo.
## Rabbit holes de produto
- **"Só completar a string nos comandos".** Se alguém apenas trocar o modelo nos frontmatters dos comandos, muda a execução de Issues (fora de escopo) e ignora o provider do gateway. **Corte neste item:** a mudança é no default de LAUNCH do worktree (preset + provider no repo), não no cardápio de execução.
- **"Configurar o gateway no global".** Se alguém criar o provider no opencode.jsonc global, vira config de máquina do humano e contamina todas as sessões. **Corte neste item:** provider no repo `opencode.json`, apenas para expor o caminho que o preset usa.
## Questões em aberto (produto)
- **Os comandos de execução de Issues acompanham o novo default ou ficam como estão?** **Opções:** A) ficam como estão (execução = escolha estável, só o launch muda) | B) alinhar também. **Recomendação:** A — o item é o default de LAUNCH; o cardápio de execução é outro mecanismo e está fora de escopo.
- **Onde expor a variante max: no provider do repo ou como flag no preset?** **Opções:** A) default no provider | B) flag nova (`--variant max`) na emissão do launch. **Recomendação:** A — default explícito no provider, mantendo a emissão atual de `--model` intacta e o teste unitário como guarda.
## Referências
- GitHub Issue #784 (registro)
- `scripts/lib/worktree.mjs` · `scripts/worktree.mjs` · `tests/unit/worktree.unit.spec.ts` · `opencode.json` · `.opencode/commands/work-issue.md` · `.opencode/commands/plan-issue.md` · `.agents/shell/worktree.sh` · `.agents/skills/worktree-next-issue/SKILL.md`

View file

@ -36,7 +36,6 @@ import { ImportPreview as ImportPreview_cdf7e044479f899a31f804427d568b36 } from
import { ImportSaveButton as ImportSaveButton_cdf7e044479f899a31f804427d568b36 } from '@payloadcms/plugin-import-export/rsc'
import { InstagramSyncStatusPanel as InstagramSyncStatusPanel_90dd38ffecf41d93e389c788f98f48da } from '../../../components/admin/InstagramSyncStatusPanel'
import { InstagramPostExclusionPicker as InstagramPostExclusionPicker_ba03418db242c21470543bbeb06827a0 } from '../../../components/admin/InstagramPostExclusionPicker'
import { S3ClientUploadHandler as S3ClientUploadHandler_f97aa6c64367fa259c5bc0567239ef24 } from '@payloadcms/storage-s3/client'
import { ImportExportProvider as ImportExportProvider_cdf7e044479f899a31f804427d568b36 } from '@payloadcms/plugin-import-export/rsc'
import { CollectionCards as CollectionCards_f9c02e79a4aed9a3924487c0cd4cafb1 } from '@payloadcms/next/rsc'
@ -79,7 +78,6 @@ export const importMap = {
"@payloadcms/plugin-import-export/rsc#ImportSaveButton": ImportSaveButton_cdf7e044479f899a31f804427d568b36,
"./components/admin/InstagramSyncStatusPanel#InstagramSyncStatusPanel": InstagramSyncStatusPanel_90dd38ffecf41d93e389c788f98f48da,
"./components/admin/InstagramPostExclusionPicker#InstagramPostExclusionPicker": InstagramPostExclusionPicker_ba03418db242c21470543bbeb06827a0,
"@payloadcms/storage-s3/client#S3ClientUploadHandler": S3ClientUploadHandler_f97aa6c64367fa259c5bc0567239ef24,
"@payloadcms/plugin-import-export/rsc#ImportExportProvider": ImportExportProvider_cdf7e044479f899a31f804427d568b36,
"@payloadcms/next/rsc#CollectionCards": CollectionCards_f9c02e79a4aed9a3924487c0cd4cafb1
}

View file

@ -1,7 +1,7 @@
'use client'
import { ChevronsUpDownIcon, XIcon } from 'lucide-react'
import { useEffect, useRef, useState } from 'react'
import { useState } from 'react'
import type { RelationOption } from '@/components/campaign/shared/RelationMultiSelect'
import { Avatar, AvatarFallback, AvatarImage } from '@/components/ui/Avatar'
@ -16,6 +16,7 @@ import {
CommandList,
} from '@/components/ui/Command'
import { Spinner } from '@/components/ui/Spinner'
import { useAsyncSearchOptions } from '@/hooks/useAsyncSearchOptions'
import { campaignUserInitials } from '@/utilities/campaignUserProfile'
export type DemandResponsibleOption = RelationOption & { avatarUrl?: string | null }
@ -60,38 +61,7 @@ export const DemandResponsibleMultiSelect = ({
const [selected, setSelected] = useState<DemandResponsibleOption[]>(value)
const [open, setOpen] = useState(false)
const [query, setQuery] = useState('')
const [options, setOptions] = useState<RelationOption[]>([])
const [loading, setLoading] = useState(false)
const [failed, setFailed] = useState(false)
const requestId = useRef(0)
const searchRef = useRef(search)
searchRef.current = search
useEffect(() => {
if (!open) return
const currentRequestId = ++requestId.current
const timeout = window.setTimeout(() => {
setLoading(true)
setFailed(false)
void searchRef
.current(query.trim())
.then((nextOptions) => {
if (requestId.current !== currentRequestId) return
setOptions(nextOptions)
})
.catch(() => {
if (requestId.current !== currentRequestId) return
setFailed(true)
})
.finally(() => {
if (requestId.current === currentRequestId) setLoading(false)
})
}, 250)
return () => window.clearTimeout(timeout)
}, [open, query])
const { options, loading, failed } = useAsyncSearchOptions({ open, query, search })
const isCreator = (id: number) => creatorUserId != null && creatorUserId === id
const selectedIds = new Set(selected.map((option) => option.id))

View file

@ -1,7 +1,7 @@
'use client'
import { ChevronsUpDownIcon } from 'lucide-react'
import { useEffect, useRef, useState } from 'react'
import { useEffect, useState } from 'react'
import { Button } from '@/components/ui/button'
import {
@ -13,6 +13,7 @@ import {
CommandList,
} from '@/components/ui/Command'
import { Spinner } from '@/components/ui/Spinner'
import { useAsyncSearchOptions } from '@/hooks/useAsyncSearchOptions'
export type AsyncSearchOption = {
id: number
@ -49,51 +50,12 @@ export const AsyncSearchCombobox = ({
const [open, setOpen] = useState(false)
const [query, setQuery] = useState('')
const [selected, setSelected] = useState<AsyncSearchOption | null>(value)
const [options, setOptions] = useState<AsyncSearchOption[]>([])
const [loading, setLoading] = useState(false)
const [failed, setFailed] = useState(false)
const requestId = useRef(0)
const searchRef = useRef(search)
const isQueryReadyRef = useRef(isQueryReady)
searchRef.current = search
isQueryReadyRef.current = isQueryReady
const { options, loading, failed } = useAsyncSearchOptions({ open, query, search, isQueryReady })
useEffect(() => {
setSelected(value)
}, [value])
useEffect(() => {
if (!open) return
if (!isQueryReadyRef.current(query)) {
setOptions([])
setLoading(false)
setFailed(false)
return
}
const currentRequestId = ++requestId.current
const timeout = window.setTimeout(() => {
setLoading(true)
setFailed(false)
void searchRef
.current(query.trim())
.then((nextOptions) => {
if (requestId.current !== currentRequestId) return
setOptions(nextOptions)
})
.catch(() => {
if (requestId.current !== currentRequestId) return
setFailed(true)
})
.finally(() => {
if (requestId.current === currentRequestId) setLoading(false)
})
}, 250)
return () => window.clearTimeout(timeout)
}, [open, query])
const choose = (option: AsyncSearchOption | null) => {
setSelected(option)
setOpen(false)

View file

@ -1,7 +1,7 @@
'use client'
import { ChevronsUpDownIcon, XIcon } from 'lucide-react'
import { useEffect, useRef, useState } from 'react'
import { useState } from 'react'
import { Badge } from '@/components/ui/Badge'
import { Button } from '@/components/ui/button'
@ -15,6 +15,7 @@ import {
} from '@/components/ui/Command'
import { Field, FieldDescription, FieldError, FieldLabel } from '@/components/ui/field'
import { Spinner } from '@/components/ui/Spinner'
import { useAsyncSearchOptions } from '@/hooks/useAsyncSearchOptions'
import { isContactSearchQueryReady } from '@/lib/contactSearchQuery'
import {
MAX_ACTIVITY_RESPONSIBLES,
@ -67,44 +68,12 @@ export const ResponsibleMultiSelect = ({
const [selected, setSelected] = useState<ResponsibleOption[]>(value)
const [open, setOpen] = useState(false)
const [query, setQuery] = useState('')
const [options, setOptions] = useState<ResponsibleOption[]>([])
const [loading, setLoading] = useState(false)
const [failed, setFailed] = useState(false)
const requestId = useRef(0)
const searchRef = useRef(search)
searchRef.current = search
useEffect(() => {
if (!open) return
if (!isContactSearchQueryReady(query)) {
setOptions([])
setLoading(false)
setFailed(false)
return
}
const currentRequestId = ++requestId.current
const timeout = window.setTimeout(() => {
setLoading(true)
setFailed(false)
void searchRef
.current(query.trim())
.then((nextOptions) => {
if (requestId.current !== currentRequestId) return
setOptions(nextOptions)
})
.catch(() => {
if (requestId.current !== currentRequestId) return
setFailed(true)
})
.finally(() => {
if (requestId.current === currentRequestId) setLoading(false)
})
}, 250)
return () => window.clearTimeout(timeout)
}, [open, query])
const { options, loading, failed } = useAsyncSearchOptions({
open,
query,
search,
isQueryReady: isContactSearchQueryReady,
})
const selectedKey = (option: ResponsibleOption) => `${option.relationTo}:${option.id}`
const selectedKeys = new Set(selected.map(selectedKey))

View file

@ -0,0 +1,76 @@
import { useEffect, useRef, useState } from 'react'
export const ASYNC_SEARCH_DEBOUNCE_MS = 250
type UseAsyncSearchOptionsResult<T> = {
options: T[]
loading: boolean
failed: boolean
}
type UseAsyncSearchOptionsArgs<T> = {
open: boolean
query: string
search: (query: string) => Promise<T[]>
isQueryReady?: (query: string) => boolean
}
/**
* E1 — the shared async-search-with-debounce effect (requestId guard against
* out-of-order responses, loading/failed states, per-consumer query gate).
* The server action is injected as a prop by the consumer, keeping this module
* client-safe; each consumer keeps its own filtering/grouping/pinned options.
* Contract quirks, preserved from the three original copies: a not-ready query
* resets options/loading/failed without invalidating an in-flight request
* (a stale response still lands after the reset), and the search receives the
* trimmed query.
*/
export function useAsyncSearchOptions<T extends { id: number }>({
open,
query,
search,
isQueryReady = () => true,
}: UseAsyncSearchOptionsArgs<T>): UseAsyncSearchOptionsResult<T> {
const [options, setOptions] = useState<T[]>([])
const [loading, setLoading] = useState(false)
const [failed, setFailed] = useState(false)
const requestId = useRef(0)
const searchRef = useRef(search)
const isQueryReadyRef = useRef(isQueryReady)
searchRef.current = search
isQueryReadyRef.current = isQueryReady
useEffect(() => {
if (!open) return
if (!isQueryReadyRef.current(query)) {
setOptions([])
setLoading(false)
setFailed(false)
return
}
const currentRequestId = ++requestId.current
const timeout = window.setTimeout(() => {
setLoading(true)
setFailed(false)
void searchRef
.current(query.trim())
.then((nextOptions) => {
if (requestId.current !== currentRequestId) return
setOptions(nextOptions)
})
.catch(() => {
if (requestId.current !== currentRequestId) return
setFailed(true)
})
.finally(() => {
if (requestId.current === currentRequestId) setLoading(false)
})
}, ASYNC_SEARCH_DEBOUNCE_MS)
return () => window.clearTimeout(timeout)
}, [open, query])
return { options, loading, failed }
}

View file

@ -0,0 +1,175 @@
import { act, renderHook } from '@testing-library/react'
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import { ASYNC_SEARCH_DEBOUNCE_MS, useAsyncSearchOptions } from '@/hooks/useAsyncSearchOptions'
type TestOption = { id: number; label: string }
const renderOptions = (
props: {
open?: boolean
query?: string
isQueryReady?: (query: string) => boolean
} = {},
) => {
const search = vi.fn(
async (query: string): Promise<TestOption[]> => [{ id: 1, label: `hit:${query}` }],
)
const view = renderHook(
(current: { open: boolean; query: string; isQueryReady?: (query: string) => boolean }) =>
useAsyncSearchOptions<TestOption>({
open: current.open,
query: current.query,
search,
...(current.isQueryReady ? { isQueryReady: current.isQueryReady } : {}),
}),
{
initialProps: {
open: props.open ?? true,
query: props.query ?? '',
...(props.isQueryReady ? { isQueryReady: props.isQueryReady } : {}),
},
},
)
return { search, view }
}
beforeEach(() => {
vi.useFakeTimers()
})
afterEach(() => {
vi.useRealTimers()
})
describe('useAsyncSearchOptions', () => {
it('waits out the debounce, then searches with the trimmed query', async () => {
const { search, view } = renderOptions({ query: ' ca ' })
expect(search).not.toHaveBeenCalled()
expect(view.result.current.loading).toBe(false)
await act(async () => void vi.advanceTimersByTime(ASYNC_SEARCH_DEBOUNCE_MS))
expect(search).toHaveBeenCalledTimes(1)
expect(search).toHaveBeenCalledWith('ca')
expect(view.result.current.options).toEqual([{ id: 1, label: 'hit:ca' }])
expect(view.result.current.loading).toBe(false)
expect(view.result.current.failed).toBe(false)
})
it('does not search while the dialog stays closed', async () => {
const { search, view } = renderOptions({ open: false, query: 'cairu' })
await act(async () => void vi.advanceTimersByTime(ASYNC_SEARCH_DEBOUNCE_MS))
expect(search).not.toHaveBeenCalled()
expect(view.result.current.options).toEqual([])
expect(view.result.current.loading).toBe(false)
})
it('coalesces rapid query changes into a single search for the last query', async () => {
const { search, view } = renderOptions({ query: 'a' })
act(() => void vi.advanceTimersByTime(ASYNC_SEARCH_DEBOUNCE_MS - 1))
view.rerender({ open: true, query: 'ab' })
await act(async () => void vi.advanceTimersByTime(ASYNC_SEARCH_DEBOUNCE_MS))
expect(search).toHaveBeenCalledTimes(1)
expect(search).toHaveBeenCalledWith('ab')
})
it('resets state without searching when the query is not ready', async () => {
const { search, view } = renderOptions({ isQueryReady: (query) => query.length >= 2 })
await act(async () => void vi.advanceTimersByTime(ASYNC_SEARCH_DEBOUNCE_MS))
expect(search).not.toHaveBeenCalled()
expect(view.result.current.options).toEqual([])
expect(view.result.current.loading).toBe(false)
expect(view.result.current.failed).toBe(false)
view.rerender({ open: true, query: 'ca', isQueryReady: (query) => query.length >= 2 })
await act(async () => void vi.advanceTimersByTime(ASYNC_SEARCH_DEBOUNCE_MS))
expect(search).toHaveBeenCalledTimes(1)
expect(search).toHaveBeenCalledWith('ca')
})
it('sets failed on a rejected search and clears loading', async () => {
const { search, view } = renderOptions({ query: 'ca' })
search.mockRejectedValueOnce(new Error('boom'))
await act(async () => void vi.advanceTimersByTime(ASYNC_SEARCH_DEBOUNCE_MS))
expect(view.result.current.failed).toBe(true)
expect(view.result.current.loading).toBe(false)
expect(view.result.current.options).toEqual([])
})
it('recovers from a failed search on the next successful one', async () => {
const { search, view } = renderOptions({ query: 'ca' })
search.mockRejectedValueOnce(new Error('boom'))
await act(async () => void vi.advanceTimersByTime(ASYNC_SEARCH_DEBOUNCE_MS))
expect(view.result.current.failed).toBe(true)
view.rerender({ open: true, query: 'cairu' })
await act(async () => void vi.advanceTimersByTime(ASYNC_SEARCH_DEBOUNCE_MS))
expect(view.result.current.failed).toBe(false)
expect(view.result.current.options).toEqual([{ id: 1, label: 'hit:cairu' }])
expect(view.result.current.loading).toBe(false)
})
it('keeps loading while the request is in flight', async () => {
const { search, view } = renderOptions({ query: 'ca' })
search.mockImplementationOnce(() => new Promise<TestOption[]>(() => {}))
act(() => void vi.advanceTimersByTime(ASYNC_SEARCH_DEBOUNCE_MS))
expect(view.result.current.loading).toBe(true)
expect(view.result.current.failed).toBe(false)
})
it('lets a stale in-flight response land after the query turns not-ready (preserved quirk)', async () => {
const { search, view } = renderOptions({ query: 'ca', isQueryReady: (q) => q.length >= 2 })
let resolveFirst: (options: TestOption[]) => void = () => {}
search.mockImplementationOnce(
() => new Promise<TestOption[]>((resolve) => (resolveFirst = resolve)),
)
act(() => void vi.advanceTimersByTime(ASYNC_SEARCH_DEBOUNCE_MS))
expect(view.result.current.loading).toBe(true)
view.rerender({ open: true, query: '', isQueryReady: (q) => q.length >= 2 })
expect(view.result.current.options).toEqual([])
expect(view.result.current.loading).toBe(false)
await act(async () => resolveFirst([{ id: 1, label: 'stale' }]))
expect(view.result.current.options).toEqual([{ id: 1, label: 'stale' }])
expect(view.result.current.loading).toBe(false)
})
it('discards an out-of-order response from a superseded request', async () => {
const { search, view } = renderOptions({ query: 'ca' })
let resolveFirst: (options: TestOption[]) => void = () => {}
search.mockImplementationOnce(
() => new Promise<TestOption[]>((resolve) => (resolveFirst = resolve)),
)
search.mockResolvedValueOnce([{ id: 2, label: 'hit:campanha' }])
act(() => void vi.advanceTimersByTime(ASYNC_SEARCH_DEBOUNCE_MS))
view.rerender({ open: true, query: 'campanha' })
await act(async () => void vi.advanceTimersByTime(ASYNC_SEARCH_DEBOUNCE_MS))
expect(search).toHaveBeenCalledTimes(2)
await act(async () => resolveFirst([{ id: 1, label: 'stale' }]))
expect(view.result.current.options).toEqual([{ id: 2, label: 'hit:campanha' }])
expect(view.result.current.loading).toBe(false)
})
})