teqo/src/utilities/municipalityUi.ts
Francisco Ignácio Fontoura Solla 31fcc20ffd E9 /simplify: consolidate duplicated helpers, dead passthrough, comment drift
Cross-checked by parallel code-quality/performance/reuse reviewers against
the E9 commit. Behavior-preserving:

- laterTimestamp/resolveMunicipalityLastSignalAt were the same "latest of
  two ISO timestamps" written twice; both now delegate to a new
  latestIsoTimestamp in campaignTime.ts, which documents the fixed-width
  UTC invariant that makes the string compare sound.
- Hoisted the frescor comparator's Date.now() out of the per-comparison
  accessor so the sort key stops drifting mid-sort.
- Deleted the unread baseTotal/growthFactor/belowBase passthrough from the
  statewide goal entry point and fixed a comment citing a symbol
  (goalDecompositionBelowBase) that never existed; renamed
  computeStatewideGoalDecomposition -> computeStatewideSuggestedGoals now
  that nothing is proportionally decomposed.
- Collapsed the advisor badge's two copies (desktop table vs mobile card)
  into one AdvisorStatusBadge; they had quietly diverged on which icon
  renders for the "no advisor" state.
- Renamed the sort-menu's stale "Cobertura" label for advisor coverage to
  "Assessoria" (E8 already renamed the list column for the same reason);
  derived the sort-key set from the label record instead of a third
  parallel list.
- Consolidated three zeroed-scenario-record literals into one
  zeroByVoteEstimateScenario() factory in voteEstimate.ts.
- Routed three separate votesByYear[2022] reads through one votesInYear
  helper in municipalityPotential.ts.
- Gated the goal card's empty-state copy on !usesMesaEstimate so it stops
  telling a município with an existing mesa estimate to enter one.
- Swapped a test assertion pinned to a raw Tailwind token for a stable
  data-signal="cold" hook, and tightened the "desert" test's bound to
  check against the actual growth factor (the old bound was true for
  every slug regardless of the formula).

Left alone (roadmap decision, not cleanup): sanityCheckSuggestedGoalsByTerritory
has no production caller yet (deferred to E11/E12); comment shortened
instead of deleting the dead-but-documented code.

Verified: tsc --noEmit, pnpm lint (0 warnings), 337 unit + 366 integration
tests, pnpm build all green.
2026-07-25 02:24:18 -03:00

460 lines
17 KiB
TypeScript
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.

import type { Where } from 'payload'
import { bahiaIdentityTerritories, type BahiaIdentityTerritory } from '@/lib/bahiaTerritories'
import { formatElectionNumber } from '@/lib/electionInsights'
import { municipalityCatalog } from '@/lib/municipalityCatalog'
import type { CampaignUser, Municipality } from '@/payload-types'
import {
buildListHref,
firstValue,
normalizedText,
resolveListUrl,
strictDecimalInteger,
type RawSearchParams as CampaignListRawSearchParams,
} from '@/utilities/campaignListUrl'
import { latestIsoTimestamp } from '@/utilities/campaignTime'
import { normalizeSearchPhrase } from '@/utilities/wordStartFilter'
export const municipalityPageSize = 25
export const municipalityKindLabels: Record<Municipality['kind'], string> = {
municipio: 'Município',
zona: 'Zona eleitoral',
}
export const municipalityPriorityLabels: Record<NonNullable<Municipality['priority']>, string> = {
alta: 'Prioritária',
normal: 'Normal',
}
export type PoliticalTrendStatus = NonNullable<NonNullable<Municipality['politicalTrend']>['status']>
export const politicalTrendLabels: Record<PoliticalTrendStatus, string> = {
favoravel: 'Favorável',
neutra: 'Neutra',
desfavoravel: 'Desfavorável',
}
export const politicalTrendBadgeVariant = {
favoravel: 'estimate-confirmed',
neutra: 'secondary',
desfavoravel: 'destructive',
} as const
export type MunicipalityListSortKey =
| 'name'
| 'region'
| 'kind'
| 'trend'
| 'expectedVotes'
| 'lastUpdateAt'
| 'coverage'
| 'votos'
| 'deficit'
| 'frescor'
export type MunicipalityListSortDirection = 'asc' | 'desc'
/**
* E9 allocation queue: the list opens on the decision it exists to serve —
* where the goal is least covered by auditable commitments (biggest deficit
* first), in the `central` scenario. Since E9 anchored the suggested goal on
* the candidate's own 2022 vote, this ordering stays close to the previous
* `votos` default instead of surfacing deserts with inflated goals.
*/
export const DEFAULT_MUNICIPALITY_LIST_SORT_KEY: MunicipalityListSortKey = 'deficit'
export const DEFAULT_MUNICIPALITY_LIST_SORT_DIR: MunicipalityListSortDirection = 'desc'
export const municipalityListSortLabels: Record<MunicipalityListSortKey, string> = {
name: 'Município',
region: 'Território de identidade',
kind: 'Tipo',
trend: 'Tendência',
expectedVotes: 'Votos estimados',
lastUpdateAt: 'Última atualização',
/** Advisor coverage — "Cobertura" alone now reads as the goal one (`deficit`). */
coverage: 'Assessoria',
/** Short header — definition lives on hover (`formatMunicipalityConcentrationHint`). */
votos: '2022',
deficit: 'Cobertura da meta',
frescor: 'Frescor do sinal',
}
export type MunicipalityListState = {
page: number
q?: string
region?: BahiaIdentityTerritory
kind?: Municipality['kind']
coverage?: 'com_assessor' | 'sem_assessor'
priority?: 'alta'
trend?: PoliticalTrendStatus
/** Candidate number for the map comparison mode (does not filter the list). */
compare?: number
sort?: MunicipalityListSortKey
dir?: MunicipalityListSortDirection
}
export type MunicipalityListSearchParams = CampaignListRawSearchParams
export const municipalityListParamNames = [
'q',
'region',
'kind',
'coverage',
'priority',
'trend',
'compare',
'sort',
'dir',
'page',
] as const
const municipalityListParamNameSet = new Set<string>(municipalityListParamNames)
// Derived from the label record (total over the union), so a new sort key is
// declared in the type and the labels only.
const municipalityListSortKeySet = new Set<string>(Object.keys(municipalityListSortLabels))
const municipalityListSortDirSet = new Set<MunicipalityListSortDirection>(['asc', 'desc'])
const sortKeysWithDescDefault: MunicipalityListSortKey[] = [
'expectedVotes',
'lastUpdateAt',
'votos',
// Both open on the worst case: biggest uncovered deficit, coldest signal.
'deficit',
'frescor',
]
export const defaultMunicipalityListSortDir = (
key: MunicipalityListSortKey,
): MunicipalityListSortDirection => (sortKeysWithDescDefault.includes(key) ? 'desc' : 'asc')
export const resolveMunicipalityListSort = (
state: MunicipalityListState,
): { sort: MunicipalityListSortKey; dir: MunicipalityListSortDirection } => {
const sort = state.sort ?? DEFAULT_MUNICIPALITY_LIST_SORT_KEY
const dir = state.dir ?? defaultMunicipalityListSortDir(sort)
return { sort, dir }
}
export const formatMunicipalityConcentrationHint = (
totalUnits: number = municipalityCatalog.length,
): string =>
`Percentual da votação estadual do candidato neste município — não o % dos válidos locais. Colocação: posição no catálogo de ${formatElectionNumber(totalUnits)} unidades.`
/**
* E9 frescor — the last time ANYBODY recorded something here: a staff update
* or a leadership pledge declaration/estimate. One rule, shared by the server
* ordering (`municipalityPageData.ts`) and the list cell, so "há N dias"
* never disagrees with the position in the queue.
*/
export const resolveMunicipalityLastSignalAt = (
lastUpdateAt: string | null,
lastPledgeAt: string | null,
): string | null => latestIsoTimestamp(lastUpdateAt, lastPledgeAt)
/**
* Days since the last signal, floored. The research report only says a
* commitment left untouched "for weeks" is worth less, so the threshold below
* is a convention (3 weeks), not a measured decay curve.
*/
export const MUNICIPALITY_COLD_SIGNAL_DAYS = 21
export const municipalitySignalAgeInDays = (
lastSignalAt: string | null,
now: Date = new Date(),
): number | null => {
if (!lastSignalAt) return null
const elapsed = now.getTime() - new Date(lastSignalAt).getTime()
if (Number.isNaN(elapsed)) return null
return Math.max(0, Math.floor(elapsed / 86_400_000))
}
export const isMunicipalitySignalCold = (ageInDays: number | null): boolean =>
ageInDays === null || ageInDays >= MUNICIPALITY_COLD_SIGNAL_DAYS
/**
* "há 3 dias" / "hoje" / "Sem sinal" — dense cell copy for the queue.
* Deliberately not `formatRelativeAge`: its `numeric: 'auto'` yields "ontem"/
* "anteontem" and minute/hour granularity, which breaks both the day-based
* cold threshold and the tabular-nums scan down the column.
*/
export const formatMunicipalitySignalAgeLabel = (ageInDays: number | null): string => {
if (ageInDays === null) return 'Sem sinal'
if (ageInDays === 0) return 'hoje'
if (ageInDays === 1) return 'há 1 dia'
return `há ${ageInDays} dias`
}
export const formatMunicipalityListSortSummary = (
sort: MunicipalityListSortKey,
dir: MunicipalityListSortDirection,
): string => {
if (sort === 'votos') {
return dir === 'desc' ? 'Ordenado por 2022 ↓' : 'Ordenado por 2022 ↑'
}
if (sort === 'name') {
return dir === 'asc' ? 'Ordenado por nome (A–Z)' : 'Ordenado por nome (Z–A)'
}
if (sort === 'deficit') {
return dir === 'desc'
? 'Ordenado por déficit da meta (maior primeiro)'
: 'Ordenado por déficit da meta (menor primeiro)'
}
if (sort === 'frescor') {
return dir === 'desc'
? 'Ordenado por frescor (sinal mais frio primeiro)'
: 'Ordenado por frescor (sinal mais recente primeiro)'
}
const label = municipalityListSortLabels[sort]
return dir === 'desc' ? `Ordenado por ${label} ↓` : `Ordenado por ${label} ↑`
}
const canonicalTerritoryBySearchValue = new Map(
bahiaIdentityTerritories.map((territory) => [normalizeSearchPhrase(territory), territory]),
)
export const parseMunicipalityListParams = (params: MunicipalityListSearchParams): MunicipalityListState => {
const rawPage = strictDecimalInteger(firstValue(params.page))
const q = normalizedText(firstValue(params.q))
const rawRegion = normalizedText(firstValue(params.region))
const region = rawRegion
? canonicalTerritoryBySearchValue.get(normalizeSearchPhrase(rawRegion))
: undefined
const rawKind = firstValue(params.kind)
const rawCoverage = firstValue(params.coverage)
const rawPriority = firstValue(params.priority)
const rawTrend = firstValue(params.trend)
const rawCompare = strictDecimalInteger(firstValue(params.compare))
const rawSort = firstValue(params.sort) as MunicipalityListSortKey | undefined
const sort = rawSort && municipalityListSortKeySet.has(rawSort) ? rawSort : undefined
const rawDir = firstValue(params.dir) as MunicipalityListSortDirection | undefined
const dir = rawDir && municipalityListSortDirSet.has(rawDir) ? rawDir : undefined
return {
page: rawPage ?? 1,
...(q ? { q } : {}),
...(region ? { region } : {}),
...(rawKind === 'municipio' || rawKind === 'zona' ? { kind: rawKind } : {}),
...(rawCoverage === 'com_assessor' || rawCoverage === 'sem_assessor'
? { coverage: rawCoverage }
: {}),
...(rawPriority === 'alta' ? { priority: 'alta' } : {}),
...(rawTrend === 'favoravel' || rawTrend === 'neutra' || rawTrend === 'desfavoravel'
? { trend: rawTrend }
: {}),
...(rawCompare && rawCompare <= 99999 ? { compare: rawCompare } : {}),
...(sort ? { sort } : {}),
...(dir ? { dir } : {}),
}
}
export const buildMunicipalityListWhere = (state: MunicipalityListState): Where => {
const filters: Where[] = []
const searchedZone = strictDecimalInteger(state.q)
if (state.q) {
const searchFilters: Where[] = [{ name: { contains: state.q } }]
if (searchedZone && searchedZone <= 999) {
searchFilters.push({ zoneNumber: { equals: searchedZone } })
}
filters.push({ or: searchFilters })
}
if (state.region) filters.push({ region: { equals: state.region } })
if (state.kind) filters.push({ kind: { equals: state.kind } })
if (state.coverage) {
filters.push({
advisors: { exists: state.coverage === 'com_assessor' },
})
}
if (state.priority) filters.push({ priority: { equals: state.priority } })
if (state.trend) {
filters.push({ 'politicalTrend.status': { equals: state.trend } })
}
return filters.length ? { and: filters } : {}
}
export const buildMunicipalityListSearchParams = (
state: MunicipalityListState,
page = state.page,
): URLSearchParams => {
const canonicalState = parseMunicipalityListParams({
page: String(page),
q: state.q,
region: state.region,
kind: state.kind,
coverage: state.coverage,
priority: state.priority,
trend: state.trend,
compare: state.compare === undefined ? undefined : String(state.compare),
sort: state.sort,
dir: state.dir,
})
const params = new URLSearchParams()
const resolvedSort = canonicalState.sort ?? DEFAULT_MUNICIPALITY_LIST_SORT_KEY
const resolvedDir = canonicalState.dir ?? defaultMunicipalityListSortDir(resolvedSort)
const isListDefault =
resolvedSort === DEFAULT_MUNICIPALITY_LIST_SORT_KEY &&
resolvedDir === defaultMunicipalityListSortDir(DEFAULT_MUNICIPALITY_LIST_SORT_KEY)
if (canonicalState.q) params.set('q', canonicalState.q)
if (canonicalState.region) params.set('region', canonicalState.region)
if (canonicalState.kind) params.set('kind', canonicalState.kind)
if (canonicalState.coverage) params.set('coverage', canonicalState.coverage)
if (canonicalState.priority) params.set('priority', canonicalState.priority)
if (canonicalState.trend) params.set('trend', canonicalState.trend)
if (canonicalState.compare) params.set('compare', String(canonicalState.compare))
// Omit the mesa default pair (votos+desc). Keep `sort` whenever the pair is
// non-default so `dir` is never orphaned (e.g. votos+asc → sort=votos&dir=asc).
if (!isListDefault) {
params.set('sort', resolvedSort)
if (resolvedDir !== defaultMunicipalityListSortDir(resolvedSort)) {
params.set('dir', resolvedDir)
}
}
if (canonicalState.page > 1) params.set('page', String(canonicalState.page))
return params
}
export const buildMunicipalityFiltersKey = (state: MunicipalityListState): string =>
buildMunicipalityListSearchParams(state).toString()
export const buildMunicipalityListHref = (state: MunicipalityListState, page: number): string =>
buildListHref(state, buildMunicipalityListSearchParams, '/campanha/municipios', page)
export const buildMunicipalitySortHref = (
state: MunicipalityListState,
nextKey: MunicipalityListSortKey,
): string => {
const currentSort = state.sort ?? DEFAULT_MUNICIPALITY_LIST_SORT_KEY
const currentDir = state.dir ?? defaultMunicipalityListSortDir(currentSort)
let dir: MunicipalityListSortDirection
if (nextKey === currentSort) {
dir = currentDir === 'asc' ? 'desc' : 'asc'
} else {
dir = defaultMunicipalityListSortDir(nextKey)
}
const updatedState: MunicipalityListState = {
...state,
sort: nextKey,
dir,
page: 1,
}
return buildMunicipalityListHref(updatedState, 1)
}
export const formatMunicipalitySortOptionLabel = (
key: MunicipalityListSortKey,
dir: MunicipalityListSortDirection,
): string => {
const base = municipalityListSortLabels[key]
if (key === 'expectedVotes' || key === 'votos') {
return dir === 'asc' ? `${base} (menor → maior)` : `${base} (maior → menor)`
}
if (key === 'lastUpdateAt') {
return dir === 'asc' ? `${base} (mais antiga)` : `${base} (mais recente)`
}
if (key === 'deficit') {
return dir === 'asc' ? `${base} (mais coberta)` : `${base} (mais descoberta)`
}
if (key === 'frescor') {
return dir === 'asc' ? `${base} (mais recente)` : `${base} (mais frio)`
}
return dir === 'asc' ? `${base} (A–Z)` : `${base} (Z–A)`
}
export const municipalityListSortOptions = (
Object.keys(municipalityListSortLabels) as MunicipalityListSortKey[]
).flatMap((key) => [
{ key, dir: 'asc' as const, label: formatMunicipalitySortOptionLabel(key, 'asc') },
{ key, dir: 'desc' as const, label: formatMunicipalitySortOptionLabel(key, 'desc') },
])
export const serializeMunicipalitySortValue = (
key: MunicipalityListSortKey,
dir: MunicipalityListSortDirection,
): string => `${key}|${dir}`
export const parseMunicipalitySortValue = (
value: string,
): { key: MunicipalityListSortKey; dir: MunicipalityListSortDirection } | null => {
const [rawKey, rawDir] = value.split('|')
if (!municipalityListSortKeySet.has(rawKey as MunicipalityListSortKey)) return null
if (!municipalityListSortDirSet.has(rawDir as MunicipalityListSortDirection)) return null
return { key: rawKey as MunicipalityListSortKey, dir: rawDir as MunicipalityListSortDirection }
}
export const shouldUpdateMunicipalitySearchUrl = (
input: string,
currentQ: string | undefined,
): boolean => normalizedText(input) !== currentQ
export const resolveMunicipalityListUrl = (
params: MunicipalityListSearchParams,
totalPages?: number,
): {
state: MunicipalityListState
href: string
redirectHref?: string
} =>
resolveListUrl({
params,
paramNameSet: municipalityListParamNameSet,
parse: parseMunicipalityListParams,
buildSearchParams: buildMunicipalityListSearchParams,
basePath: '/campanha/municipios',
totalPages,
})
export const municipalityListCoverageLabels: Record<NonNullable<MunicipalityListState['coverage']>, string> = {
com_assessor: 'Com assessor',
sem_assessor: 'Sem assessor',
}
const MAX_MUNICIPALITY_LIST_VISIT_LABEL_LENGTH = 80
export const buildMunicipalityListVisitLabel = (state: MunicipalityListState): string | null => {
const parts: string[] = []
if (state.region) parts.push(state.region)
if (state.kind) parts.push(municipalityKindLabels[state.kind])
if (state.coverage) parts.push(municipalityListCoverageLabels[state.coverage])
if (state.priority) parts.push(municipalityPriorityLabels.alta)
if (state.trend) parts.push(`Tendência ${politicalTrendLabels[state.trend].toLowerCase()}`)
if (state.q) parts.push(`Busca "${state.q}"`)
if (!parts.length) return null
const label = `Municípios · ${parts.join(' · ')}`
if (label.length <= MAX_MUNICIPALITY_LIST_VISIT_LABEL_LENGTH) return label
return `${label.slice(0, MAX_MUNICIPALITY_LIST_VISIT_LABEL_LENGTH - 1)}…`
}
export const buildMunicipalityListVisitHref = (state: MunicipalityListState): string =>
buildMunicipalityListHref(state, 1)
export const getCampaignScopeLabel = (role: CampaignUser['role'], municipalityCount: number): string => {
if (role === 'advisor') {
return `${municipalityCount} ${municipalityCount === 1 ? 'município sob sua assessoria' : 'municípios sob sua assessoria'}`
}
if (role === 'leader') {
return `${municipalityCount} ${municipalityCount === 1 ? 'município em que você atua' : 'municípios em que você atua'}`
}
return `${municipalityCount} ${municipalityCount === 1 ? 'município' : 'municípios'}`
}
/** Short human description of a municipality's geography, e.g. "Chapada Diamantina · ZE 105". */
export const formatMunicipalityGeographyLabel = (municipality: {
region: string
kind: Municipality['kind']
zoneNumber?: number | null
}): string =>
municipality.kind === 'zona' && municipality.zoneNumber != null
? `${municipality.region} · ZE ${municipality.zoneNumber}`
: municipality.region