Brasil Map React

Mapa interativo do Brasil em SVG para React. Gera SVGs leves e interativos a partir de GeoJSON, sem dependências de bibliotecas de mapas pesadas.

📚 Documentação

Início Rápido

• Quick Start - Guia rápido de instalação e uso
• Guia de Início - Guia detalhado de início
• Exemplos Práticos - Landing page com exemplos interativos

Documentação Técnica

• Referência de API - APIs e interfaces completas
• Arquitetura - Arquitetura e princípios de design
• Guias Práticos - Guias de uso avançado

Desenvolvimento

• Setup - Configuração do ambiente
• Testes - Guia de testes
• Build e Deploy - Processo de build

Segurança

• Análise de Segurança - Política de segurança

Contribuindo

• CONTRIBUTING.md - Guia para contribuidores
• CHANGELOG.md - Histórico de versões

Instalação

Via npm

npm install @syntelnet/brasil-map-react

Dependências peer:

• react >= 16.8.0
• react-dom >= 16.8.0

Via GitHub Packages (Alternativa)

Se o pacote também estiver disponível no GitHub Packages:

npm install @syntelnet/brasil-map-react

Para usar GitHub Packages, você precisa configurar autenticação. Veja a seção Configuração do GitHub Packages abaixo.

Uso Básico

import { BrasilMap } from '@syntelnet/brasil-map-react'
import '@syntelnet/brasil-map-react/dist/style.css'

function App() {
  return <BrasilMap />
}

💡 Dica: Para um guia mais rápido, consulte QUICK_START.md

Uso Avançado

import { BrasilMap } from '@syntelnet/brasil-map-react'
import '@syntelnet/brasil-map-react/dist/style.css'

function App() {
  const highlightedCities = {
    'SP': new Set(['3550308', '3509502']), // São Paulo, Campinas
    'BA': new Set(['2927408']) // Salvador
  }

  return (
    <BrasilMap
      highlightedCities={highlightedCities}
      onStateClick={(uf) => console.log('Estado:', uf)}
      onCityClick={(city) => console.log('Cidade:', city)}
      width={1000}
      height={1000}
      showStateLabels={true}
    />
  )
}

Props

BrasilMap

| Prop | Tipo | Padrão | Descrição | |------|------|--------|-----------| | highlightedCities | Object<string, Set<string>> | {} | Cidades destacadas por estado (IDs IBGE) | | onStateClick | (uf: string) => void | - | Callback quando um estado é clicado | | onCityClick | (city: {id: string, name: string}) => void | - | Callback quando uma cidade é clicada | | onInfoChange | (text: string) => void | - | Callback quando a informação muda | | width | number | 1000 | Largura da viewBox do SVG | | height | number | 1000 | Altura da viewBox do SVG | | geoBaseUrl | string | "/geo/" | URL base para os GeoJSONs | | showStateLabels | boolean | true | Exibir siglas dos estados | | showBackButton | boolean | true | Exibir botão de voltar (ícone) | | className | string | "" | Classe CSS adicional |

Hook useBrasilMap

Para uso mais avançado, você pode usar o hook diretamente:

import { useBrasilMap } from '@syntelnet/brasil-map-react'

function CustomMap() {
  const mapRef = useRef(null)
  const { renderBrasil, loadState, isStateView } = useBrasilMap({
    containerRef: mapRef,
    highlightedCities: { /* ... */ },
    onStateClick: (uf) => { /* ... */ }
  })

  return <div ref={mapRef} />
}

GeoJSONs

Os GeoJSONs estão incluídos no pacote em public/geo/. Por padrão, o componente espera que eles estejam acessíveis em /geo/ no servidor.

Para usar em produção, você pode:

1. Copiar a pasta public/geo do pacote para seu projeto
2. Configurar um CDN para servir os GeoJSONs
3. Usar a prop geoBaseUrl para apontar para a localização correta

Requisitos

• React >= 16.8.0
• React-DOM >= 16.8.0

Configuração do GitHub Packages

1. Criar Personal Access Token (PAT)

1. Vá em GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)
2. Clique em "Generate new token (classic)"
3. Dê um nome e selecione o escopo write:packages e read:packages
4. Copie o token gerado

2. Configurar autenticação

Crie um arquivo .npmrc na raiz do seu projeto (ou na sua home ~/.npmrc):

@syntelnet:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=SEU_TOKEN_AQUI

Substitua:

• @syntelnet pelo seu usuário/organização do GitHub
• SEU_TOKEN_AQUI pelo token que você criou

3. Publicar o pacote

npm publish

O pacote será publicado em: https://github.com/syntelnet/brasil-map/packages

4. Instalar em outro projeto

No projeto que vai usar o pacote, crie/edite o .npmrc:

@syntelnet:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=SEU_TOKEN_AQUI

Depois instale:

npm install @syntelnet/brasil-map-react

Segurança

Este pacote implementa várias medidas de segurança:

• ✅ Sanitização de SVG e atributos HTML
• ✅ Validação de URLs
• ✅ Validação de inputs do usuário
• ✅ Validação de estrutura GeoJSON
• ✅ Testes de segurança completos

Para mais detalhes, consulte docs/security/security-analysis.md.

Content Security Policy (CSP)

Recomendamos usar CSP em produção:

Content-Security-Policy: default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline';

Limitações

• O pacote é client-side apenas
• GeoJSONs devem ser de fontes confiáveis
• geoBaseUrl deve ser validado se fornecido pelo usuário

Recursos Adicionais

• Documentação Completa: Veja docs/README.md para índice completo
• Troubleshooting: Consulte docs/guides/troubleshooting.md para solução de problemas
• Uso Avançado: Veja docs/guides/advanced-usage.md para exemplos avançados

Contribuindo

Contribuições são bem-vindas! Consulte CONTRIBUTING.md para o guia completo de contribuição.

Licença

MIT

Desenvolvido com ❤️ para a comunidade React brasileira