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