npm package: @syntelnet/brasil-map-react
Description: Mapa interativo do Brasil em SVG para React
Latest version: 1.0.1

# Brasil Map React

<div align="center">
  <img src="https://raw.githubusercontent.com/syntelnet/react-brazil-map/master/public/geo/react-map.png" alt="Brasil Map React - Mapa Interativo do Brasil" width="800" />
</div>

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](./QUICK_START.md)** - Guia rápido de instalação e uso
- **[Guia de Início](./docs/getting-started.md)** - Guia detalhado de início
- **[Exemplos Práticos](./examples/)** - Landing page com exemplos interativos

### Documentação Técnica
- **[Referência de API](./docs/api-reference.md)** - APIs e interfaces completas
- **[Arquitetura](./docs/architecture.md)** - Arquitetura e princípios de design
- **[Guias Práticos](./docs/guides/)** - Guias de uso avançado

### Desenvolvimento
- **[Setup](./docs/development/setup.md)** - Configuração do ambiente
- **[Testes](./docs/development/testing.md)** - Guia de testes
- **[Build e Deploy](./docs/development/building.md)** - Processo de build

### Segurança
- **[Análise de Segurança](./docs/security/security-analysis.md)** - Política de segurança

### Contribuindo
- **[CONTRIBUTING.md](./CONTRIBUTING.md)** - Guia para contribuidores
- **[CHANGELOG.md](./CHANGELOG.md)** - Histórico de versões

## Instalação

### Via npm

```bash
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:

```bash
npm install @syntelnet/brasil-map-react
```

Para usar GitHub Packages, você precisa configurar autenticação. Veja a seção [Configuração do GitHub Packages](#configuração-do-github-packages) abaixo.

## Uso Básico

```jsx
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](./QUICK_START.md)

## Uso Avançado

```jsx
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:

```jsx
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

```bash
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:

```bash
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](./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](./docs/README.md) para índice completo
- **Troubleshooting**: Consulte [docs/guides/troubleshooting.md](./docs/guides/troubleshooting.md) para solução de problemas
- **Uso Avançado**: Veja [docs/guides/advanced-usage.md](./docs/guides/advanced-usage.md) para exemplos avançados

## Contribuindo

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

## Licença

MIT

---

**Desenvolvido com ❤️ para a comunidade React brasileira**