@sevn/elections-components 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sevn Technologies
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,297 @@
+# @sevn/elections-components
+
+Componentes de apuração eleitoral em tempo real: mapas, rankings, progresso de
+urnas, comparação entre turnos. São **JavaScript puro** — funcionam em qualquer
+site, com ou sem framework, com ou sem build.
+
+```js
+import { Core, StateLeaders } from '@sevn/elections-components';
+
+Core.applyKey('minha-chave-aqui');
+
+const componente = new StateLeaders({
+	target: document.querySelector('#placeholder-state-leaders')
+});
+```
+
+---
+
+## Instalação
+
+```sh
+npm install @sevn/elections-components
+```
+
+Não há dependência de peer para instalar. Svelte é detalhe de implementação
+interno: ele vai embutido no pacote e não aparece na sua árvore de dependências.
+
+## A chave
+
+Todo componente precisa de uma chave antes de buscar dados. Ela identifica sua
+CDN — é o subdomínio da API dedicada à sua conta:
+
+```js
+Core.applyKey('minha-chave-aqui');
+// → https://minha-chave-aqui-api1.sevnelections.com
+```
+
+Chame uma vez, no boot da aplicação, antes de montar qualquer componente. Sem
+chave o componente monta normalmente e exibe a mensagem de configuração
+faltando na própria área dele — nunca lança um erro que derrube sua página.
+
+### Alta disponibilidade
+
+Cada requisição tenta, em ordem:
+
+1. `{chave}-api1.sevnelections.com` — 3 tentativas
+2. `{chave}-api2.sevnelections.com` — 3 tentativas
+3. `failover-api.sevntech.com` — servidor genérico de emergência
+
+Depois de cair para um secundário, o cliente fica nele por 2 minutos antes de
+retentar o primário, para não pagar os timeouts a cada requisição num dia de
+pico. Respostas 4xx **não** promovem host: um 404 significa "recorte ainda não
+publicado", e é a resposta correta, não uma falha.
+
+O cache é compartilhado entre os hosts — trocar de servidor não invalida nada
+do que já foi baixado.
+
+## As três formas de usar
+
+### 1. Import (Node, Bun, Deno, Vite, webpack, Next, Nuxt…)
+
+```js
+import { Core, StateLeaders } from '@sevn/elections-components';
+
+Core.applyKey('minha-chave-aqui');
+
+const componente = new StateLeaders({
+	target: document.querySelector('#placeholder'),
+	year: 2026,
+	defaultOffice: 'governor'
+});
+
+// Quando não precisar mais dele:
+componente.destroy();
+```
+
+O pacote é tree-shakeable: importar um componente não traz os outros 24.
+
+### 2. Tag `<script>`, em HTML cru
+
+```html
+<div id="placeholder-state-leaders"></div>
+
+<script src="https://cdn.sevnelections.com/components/v1/state-leaders.js?cid=minha-chave-aqui"></script>
+<script>
+	const componente = new StateLeaders({
+		target: document.querySelector('#placeholder-state-leaders')
+	});
+</script>
+```
+
+A chave sai do `?cid=` da própria tag — não há o que configurar. Cada arquivo
+expõe a classe com o nome do componente (`window.StateLeaders`) e também
+`window.SevnElections.Core`, se você precisar ajustar algo.
+
+Um arquivo por componente, ~34 KB gzip cada, tudo embutido.
+
+### 3. CommonJS
+
+```js
+const { Core, StateLeaders } = require('@sevn/elections-components');
+```
+
+## API
+
+### `new Componente(opções)`
+
+`target` é obrigatório e aceita um elemento ou um seletor CSS. As demais chaves
+são as props do componente.
+
+```js
+new StateLeaders({ target: '#ph', year: 2026, mock: true });
+```
+
+### `componente.destroy()`
+
+Desmonta e remove do DOM. Devolve uma `Promise`, caso você precise esperar a
+saída terminar. Chamar duas vezes não faz nada.
+
+### `Core`
+
+| Método                                     | Para quê                                      |
+| ------------------------------------------ | --------------------------------------------- |
+| `Core.applyKey(chave)`                     | Configura a conta. Obrigatório.               |
+| `Core.setTheme({ primary, secondary, … })` | Sobrescreve as cores.                         |
+| `Core.configure(opções)`                   | Ajusta hosts, CDN de assets, cache, timeouts. |
+| `Core.getConfig()`                         | Lê a configuração atual.                      |
+| `Core.isReady()`                           | Diz se já há hosts resolvidos.                |
+| `Core.activeHost()`                        | Host que respondeu por último. Diagnóstico.   |
+
+## Estilo
+
+O CSS é injetado sozinho no momento em que o componente monta. Não há folha
+para linkar.
+
+Os componentes **herdam a tipografia da sua página** e trazem o próprio reset
+escopado às raízes `sevn_*` — nada do que eles definem vaza para o resto do
+seu site.
+
+As cores são custom properties com prefixo `--sevn-`, então você pode
+sobrescrevê-las pela cascata:
+
+```css
+:root {
+	--sevn-color-primary: #0a3e27;
+	--sevn-color-secondary: #c38214;
+}
+```
+
+Ou pela API, que dá no mesmo:
+
+```js
+Core.setTheme({ primary: '#0a3e27', secondary: '#c38214' });
+```
+
+Se preferir carregar os tokens antes do JS, o arquivo também é publicado:
+
+```js
+import '@sevn/elections-components/styles.css';
+```
+
+### Props comuns
+
+Todos os 25 componentes aceitam:
+
+| Prop       | Tipo          | Padrão         | Para quê                                                                                          |
+| ---------- | ------------- | -------------- | ------------------------------------------------------------------------------------------------- |
+| `mock`     | `boolean`     | `false`        | Renderiza com dados de exemplo, sem tocar na API. Útil para montar o layout antes de ter a chave. |
+| `rawStyle` | `boolean`     | `false`        | Remove o cartão externo (borda, fundo, respiro) para encaixar no seu layout.                      |
+| `header`   | `HeaderProps` | por componente | `{ title, description, tag, tagColor }` — o cabeçalho exibido no topo.                            |
+
+## Catálogo
+
+| Componente                                         | Arquivo UMD                                                 | Título padrão                                      | Props próprias                                                                                                                             |
+| -------------------------------------------------- | ----------------------------------------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `FinalResults`                                     | `final-results.js`                                          | Presidente                                         | `showAd: boolean` = `true`<br>`data: any \| null`<br>`stateResults: StateResults \| null`                                                  |
+| `StateWinners`                                     | `state-winners.js`                                          | Quem ganhou em cada estado                         | `data: any \| null`                                                                                                                        |
+| `VoteCountingProgress`                             | `vote-counting-progress.js`                                 | Evolução da apuração                               | `data: HeadToHeadLiveTimeline \| null`                                                                                                     |
+| `VoteComparisonByRound`                            | `vote-comparison-by-round.js`                               | Comparação de votos entre 1º e 2º turno            | `defaultOffice: 'president' \| 'governor'` = `'president'`                                                                                 |
+| `CountingProgress`                                 | `counting-progress.js`                                      | Progresso da Apuração                              | `year: number` = `2026`<br>`defaultOffice: 'president' \| 'governor'` = `'president'`                                                      |
+| `StateLeaders`                                     | `state-leaders.js`                                          | Veja quem lidera em cada estado                    | `year: number` = `2026`<br>`defaultOffice: 'president' \| 'governor'` = `'president'`                                                      |
+| `CurrentLeader`                                    | `current-leader.js`                                         | Liderança Atual                                    | `data: any \| null`                                                                                                                        |
+| `TopDispute`                                       | `top-dispute.js`                                            | Disputa no topo                                    | `year: number` = `2026`                                                                                                                    |
+| `CandidateRanking`                                 | `candidate-ranking.js`                                      | Posições de liderança                              | `year: number` = `2026`                                                                                                                    |
+| `LiveSummary`                                      | `live-summary.js`                                           | Resumo em tempo real                               | `data: any \| null`                                                                                                                        |
+| `CandidatePerformanceByMunicipality`               | `candidate-performance-by-municipality.js`                  | Consulte o desempenho dos candidatos por município | `year: number` = `2026`<br>`defaultOffice: 'president' \| 'governor'` = `'president'`                                                      |
+| `RoundResultsAnalysis`                             | `round-results-analysis.js`                                 | Análise de resultados por turno                    | `year: number` = `2026`<br>`defaultOffice: 'president' \| 'governor'` = `'president'`                                                      |
+| `ElectionStatus`                                   | `election-status.js`                                        | Situação eleitoral                                 | `year: number` = `2026`<br>`defaultOffice: 'president' \| 'governor'` = `'president'`                                                      |
+| `CandidateResultsByMunicipality`                   | `candidate-results-by-municipality.js`                      | Consulte o desempenho dos candidatos por município | `year: number` = `2026`                                                                                                                    |
+| `MunicipalityPerfomanceMap`                        | `municipality-perfomance-map.js`                            | Consulte o desempenho dos candidatos por município | `data: any \| null`<br>`year: number` = `2026`                                                                                             |
+| `CandidateByState`                                 | `candidate-by-state.js`                                     | Governador por Estado                              | `data: any \| null`<br>`year: number` = `2026`                                                                                             |
+| `CandidateCarrouselStateResultsViewer`             | `candidate-carrousel-state-results-viewer.js`               | Governador                                         | `year: number` = `2026`<br>`office: string` = `'governor'`                                                                                 |
+| `CandidateDuelStateResultViewer`                   | `candidate-duel-state-result-viewer.js`                     | Governador                                         | `data: any \| null`<br>`year: number` = `2026`<br>`showPosition: boolean` = `false`<br>`positionTagColor: string`                          |
+| `CandidateMapByState`                              | `candidate-map-by-state.js`                                 | Governador por Estado                              | `data: any \| null`                                                                                                                        |
+| `ElectionRoundAnalysis`                            | `election-round-analysis.js`                                | Análise de resultados por turno                    | `year: number` = `2026`                                                                                                                    |
+| `CandidateMultiRingChartPerformanceByMunicipality` | `candidate-multi-ring-chart-performance-by-municipality.js` | Consulte o desempenho dos candidatos por município | `year: number` = `2026`                                                                                                                    |
+| `ResultsByOffice`                                  | `results-by-office.js`                                      | Resultados por cargo                               | `year: number` = `2026`<br>`defaultOffice: 'senator' \| 'federal_deputy' \| 'state_deputy'` = `'senator'`<br>`itemsPerPage: number` = `10` |
+| `VotingMap`                                        | `voting-map.js`                                             | Mapa de Votação                                    | `showAd: boolean` = `false`<br>`year: number` = `2026`<br>`round: number` = `1`                                                            |
+| `CandidateCountingProgress`                        | `candidate-counting-progress.js`                            | Evolução da Apuração para Governador               | `year: number` = `2026`                                                                                                                    |
+| `PartyPerformance`                                 | `party-performance.js`                                      | Desempenho por Partido (senador/deputado)          | `year: number` = `2026`                                                                                                                    |
+
+## Limitações conhecidas
+
+Os tamanhos internos usam `rem`, que resolve contra o `font-size` do `<html>`
+da sua página. Se você usa a técnica de `html { font-size: 62.5% }`, os
+componentes vão encolher junto. Enquanto isso não muda, contorne isolando o
+container:
+
+```css
+#placeholder {
+	font-size: 16px;
+}
+html {
+	font-size: 100%;
+}
+```
+
+## Desenvolvimento
+
+Este repositório contém tanto a biblioteca quanto o showcase que a demonstra.
+
+```sh
+bun install
+bun run dev          # showcase em http://localhost:4321
+bun run check        # svelte-check
+bun run test         # testes unitários (transporte, config)
+```
+
+Empacotamento:
+
+```sh
+bun run build:pkg    # ESM + CJS + tipos + estilos + 25 bundles UMD
+bun run test:types   # type-check de um consumidor contra o dist publicado
+bun run serve:test   # sobe test/umd.html para exercitar o UMD no navegador
+bun run build:cdn    # monta dist-cdn/ na estrutura do R2
+```
+
+Os componentes são escritos em Svelte 5 (`src/components`), sobre primitivos
+internos (`src/lib`). Nada de `src/lib` é público: mudanças ali não são
+breaking changes. O que o consumidor vê é `src/index.ts` — classes JS geradas
+por `defineComponent`, com as props tipadas em `src/components/props.ts`.
+
+O showcase é SvelteKit, mas **o pacote não é**: `vite.lib.config.ts` e
+`scripts/build-umd.mjs` não usam o plugin do SvelteKit. O `@sveltejs/package`
+não é usado em lugar nenhum — ele não bundla, só copia `.svelte`, e era
+exatamente isso que obrigava o consumidor a ter Svelte.
+
+### Publicação
+
+```sh
+npm publish          # prepublishOnly roda build, testes e publint
+```
+
+### Subindo os arquivos para o R2
+
+São ~5.600 arquivos, e o **dashboard da Cloudflare aceita no máximo 100 por
+upload** — então esta parte é obrigatoriamente pela CLI.
+
+```sh
+wrangler login                                     # uma vez, interativo
+bun run build:cdn                                  # gera dist-cdn/
+node scripts/upload-cdn.mjs --bucket=SEU_BUCKET --dry-run   # confere antes
+node scripts/upload-cdn.mjs --bucket=SEU_BUCKET
+node scripts/upload-cdn.mjs --bucket=SEU_BUCKET --cors      # uma vez só
+```
+
+O `wrangler r2 object put` envia um objeto por vez, então o script paraleliza
+(12 por padrão, `--concurrency=N` para mudar) e grava um manifesto em
+`dist-cdn/.uploaded.json`. Se cair no meio, rodar o mesmo comando retoma de
+onde parou em vez de recomeçar os 5.600. `--force` ignora o manifesto,
+`--only=components` sobe apenas os bundles UMD — que é o caso quando você
+republica o pacote sem ter mexido nos mapas.
+
+Cada objeto sobe com `cache-control: public, max-age=31536000, immutable`,
+porque os caminhos são versionados: o conteúdo de uma chave `/v1/` nunca muda,
+mudar significa publicar `/v2/`.
+
+O `--cors` aplica o `r2-cors.json` do repositório. Sem isso o `fetch` dos mapas
+falha a partir do domínio do cliente — é requisição cross-origin.
+
+Depois de subir, falta apontar o domínio (`wrangler r2 bucket domain add`).
+
+**Alternativa mais rápida**, se você for repetir isso com frequência: o R2 tem
+API compatível com S3, então o `rclone` funciona e faz upload incremental de
+verdade (só o que mudou), com muito mais paralelismo — cada `wrangler r2 object
+put` paga o custo de subir um processo Node.
+
+```sh
+rclone sync dist-cdn/ r2:SEU_BUCKET/ --transfers=32 --checksum
+```
+
+Requer configurar um remote `r2` com um token de API do R2 (`rclone config`,
+tipo `s3`, provider `Cloudflare`).
+
+## Licença
+
+MIT