teqo-backup/.cursor/rules/campanha-action-feedback.mdc
Francisco Ignácio Fontoura Solla adc0f31f5b Sync all project docs with the deployed remodel and hardening; compile roadmap
- Compile docs/roadmap.md into a next-steps document (277→206 lines): R0–R5/M1–M5
  tables and the delivered map/list item paragraphs compressed into 'Já entregue';
  janelas, grafo and cortes list only open IDs; C10/C11/C8 fill-ins keep their
  original triggers; C5 moved under 'A validar'.
- Record the production deploy of the destructive remodel chain (2026-07-23 Vercel
  builds) across roadmap, AGENTS.md, the project notebook and plans — supersedes
  every 'deploy pendente'; smoke pós-deploy + onboarding remain the open blockers.
- Fix AGENTS.md internal contradictions: Município locked-decisions bullet (435,
  Camaçari whole, candidate role), campaignUser role enum, deploy-checklist item 7
  as historical, access/* structure note, election-aggregates artifact +
  election-tse revalidate runbook.
- Sync open plans to real identifiers (plaza*/nucleus* → municipality*): the
  intelligence program (master + E8–E15/B13/C12 with artifact/caching context and
  satisfied deps), B8 rescoped to Salvador ZE 1–19 only, WhatsApp D3–D5, D2, A6
  (now the insight layer over stateDeputy), RS+, onda-0 smoke step.
- Close items verified done in code: C8 F4 (DRY de forms) complete, filtros-auto
  shared pending shell, petition generateStaticParams select/depth; ledger the
  surviving user-visible 'Praça' copy in src as new P2 debt.
- Banner delivered praça-era plans (production note + rename pointer); mark
  remodelagem-pracas.md superseded and remodelagem-municipios.md delivered.
- TECH-DEBT smell statuses, TESTING RBAC row, README quality gates, campanha
  UI rules updated to current component names.
2026-07-24 02:04:45 -03:00

28 lines
2.7 KiB
Text

---
description: Immediate action feedback, pending UI, and optimistic controls (campanha + public)
globs: src/app/(campaign)/**/*,src/components/campaign/**/*,src/app/(frontend)/**/*,src/components/**/*
alwaysApply: false
---
# Feel the action
Canonical principle: `PRODUCT.md` § Design Principles — **Feel the action**. Precedents: `ActionPlanFilters` / `MunicipalityFilters` / `SupporterFilters` (`useTransition` + `data-pending` + `aria-busy` + live region); shared list pending via `CampaignListPendingBoundary` + `useCampaignListPending` (`CampaignListPending.tsx`, hardening 2026-07-23); form submits with `useActionState` pending + `Spinner`.
When adding or changing an interactive control that triggers navigation, revalidation, or a server action:
1. **Immediate feedback on the trigger (<~100ms).** The control must change state at once — selected value, pressed/disabled, spinner on the button — so the user knows the tap registered. Do not leave a select bound only to stale server props while RSC is still loading.
2. **Optimistic on the control; honest on the result.** Keep local/optimistic state for filter selects, toggles, and draft input. Keep the server (URL + RSC / action result) as source of truth for lists, maps, KPIs, and persisted fields — show pending on _that_ region until refresh completes; roll back the control if the action fails.
3. **Pending pattern.** Prefer `useTransition` (URL/`router`) or `useActionState`/`pending` (mutations). Set `aria-busy` and a polite live region (e.g. “Atualizando resultados…”, “Salvando…”). Dim or skeleton the changing region (`data-pending`); do not rely on `sr-only` alone when the wait is multi-second.
4. **Classify before coding.** (a) URL filter/nav → local control value + transition pending on results. (b) Form mutation → disable submit + spinner/label. (c) Lazy/heavy open → keep trigger mounted; loading/error states on the shell (existing campaign lazy-dialog pattern).
5. **Does not override Edit where you see.** In-context edit still revalidates; this rule forbids silent waits and stale-looking controls, not server refresh. Anti-goal shared with that principle: inventing list/aggregate data client-side and skipping refresh.
## Anti-goals
- Control stuck on the previous value until navigation finishes (classic filter-select bug)
- Full-page spinner as the only pending signal
- Fake/indeterminate progress that implies completion percentage
- Pending with no `aria-busy` / live region on multi-second waits
## Plan / Impeccable brief
For UI items: answer explicitly — _does every action on this surface feel immediate on the control, with honest pending on the result?_ Cite this principle; name rabbit hole “optimistic list without refresh” when scoping.