@ijusplab/svg-mapa NPM

Componente criado em Vue para a renderização de mapa interativo em svg da Seção Judiciária.

O mapa é descrito inteiramente em um objeto Javascript, com ou sem metadados de agrupamento das unidades territoriais (definidos em outro objeto Javascript), permitindo customização de tamanho, cores e isolamento de partes do mapa para visualização destacada.

O componente permite também captar eventos de clique em cada uma das unidades territoriais, retornando o código da unidade e, se houver, do grupo ao qual ela pertence.

O screenshot abaixo ilustra o mapa da Seção Judiciária de São Paulo, com suas Subseções, renderizado pelo componente:

1. Incluindo o componente em seu projeto

Para incorporar o componente ao seu projeto, digite:

yarn add @ijusplab/svg-mapa

// ou

npm install @ijusplab/svg-mapa --save

Alternativamente, no Laravel, você pode instalar o componente como dependência de desenvolvimento:

yarn add -D @ijusplab/svg-mapa

// ou

npm install @ijusplab/svg-mapa --save-dev

Em seguida, você porde importar o componente para uso em seu projeto do seguinte modo:

import SvgMapa from '@ijusplab/svg-mapa';
import '@ijusplab/svg-mapa/dist/svg-mapa.css';

...

export default {
  name: 'app',
  components: {
    SvgMapa
  },
  ...

}

2. Configurando o mapa

Os parâmetros do mapa devem ser fornecidos pelo desenvolvedor, conforme descrito a seguir.

1.1. A aplicação deve fornecer ao componente um objeto Javascript, com a estrutura dada pelo json a seguir.

{
    "title": {
        "name": "Seção Judiciária de São Paulo",
        "style": {
            "fill": "#212121",
            "font-family": "Segoe UI",
            "font-size": 24,
            "font-weight": "normal"
        },
        "containerStyle": {
            "stroke": "#212121",
            "stroke-width": "2px",
            "fill": "#E0E0E0",
            "rx": "5px",
            "ry": "5px",
            "padding": "5px"
        },
        "off-set": {
            "x": 220,
            "y": 310
        }
    },
    "svg": {
        "width": "1086.4963",
        "height": "707.90271",
        "viewBox": "0 0 1086.4963 707.90271",
        "style": {
            "stroke": "#ffffff",
            "stroke-width": "0.1px",
            "stroke-linecap": "butt",
            "stroke-linejoin": "miter"
        }
    },
    "paths": [ // array de paths (cada path deve corresponder a uma unidade territorial)
        {
            "name": "..." // nome da unidade,
            "label": {
                "style": {
                    "fill": "#000000",
                    "font-family": "Segoe UI",
                    "font-size": "16px",
                    "font-weight": "bold",
                    "stroke": "#ffffff",
                    "stroke-width": "0px",
                    "stroke-linecap": "round"
                },
                "containerStyle": {
                    "stroke": "#212121",
                    "stroke-width": "0px",
                    "fill": "none",
                    "rx": "5px",
                    "padding": "5px"
                },
                "off-set": { // off-set em relação ao centroid calculado automaticamente
                    "x": 0,
                    "y": 0
                }
            },
            "id": 5, // código numérico
            "d": "...", // elemento <d></d> do path
            "style": { // parâmetro opcional; na ausência, aplica-se o estilo do grupo ou um estilo default
                "stroke": "#ffffff",
                "stroke-width": "0.1px",
                "stroke-linecap": "round"
            }
        },
        ...
    ]
}

1.2. Opcionalmente, os paths podem ser agrupados fornecendo ao componente um objeto com a seguinte estrutura:

{
    "name": "...", // nome do agrupamento
    "groups": [ // array com os grupos pertencentes ao agrupamento
        {
            "name": "Presidente\nPrudente", // utilize \n para dividir o texto
            "label": {
                "style": {
                    "fill": "#000000",
                    "font-family": "Segoe UI",
                    "font-size": "10",
                    "font-weight": "bold",
                    "stroke": "#ffffff",
                    "stroke-width": "0px",
                    "stroke-linecap": "round"            
                },
                "containerStyle": {
                    "stroke": "#212121",
                    "stroke-width": "0px",
                    "fill": "none",
                    "rx": "5px",
                    "padding": "5px"
                },
                "off-set": { // off-set em relação à posição do centroid calculado automaticamente
                    "x": 2,
                    "y": -10
                }
            },
            "id": 30,
            "paths": [ 30 ],
            "style": { // parâmetro opcional; na ausência, aplica-se o estilo default
                "fill": "#FFEBEE",
                "stroke": "#ffffff",
                "stroke-width": "3px",
                "stroke-linecap": "round"            
            }
        },
        ...
    ]
}

1.3. Também opcionalmente, os paths podem ser coloridos segundo o padrão fornecido por um objeto chart com a estrutura abaixo. Sendo habilitada a opção de exibir legenda, o componente criará a legenda automaticamente.

{
    "name": "Teste",
    "legend": {
        "width": 300,
        "height": 100,
        "x": 30,
        "y": 480
    },
    "groups": [
        {
            "name": "Item 1",
            "label": {
                "style": {
                    "fill": "#000000",
                    "font-family": "Segoe UI",
                    "font-size": "20",
                    "font-weight": "bold",
                    "stroke": "#ffffff",
                    "stroke-width": "0px",
                    "stroke-linecap": "round"            
                },
                "containerStyle": {
                    "stroke": "#212121",
                    "stroke-width": "1px",
                    "fill": "#E0E0E0",
                    "rx": "5px",
                    "padding": "5px"
                },
                "off-set": {
                    "x": null,
                    "y": null
                }
            },
            "paths": [
                40, 17, 25, 33, 35, 26, 27, 8
            ],
            "style": {
                "fill": "#90CAF9"
            }
        },
        ...
    ]
}

1.4. Observação: os parâmetros style e containerStyle nos três objetos acima podem receber qualquer propriedade CSS aplicável aos elementos do svg. O containerStyle permite, ainda, a utilização das propriedades padding, padding-top, padding-bottom, padding-left e/ou padding-right, que são convertidas em espaçamento entre o texto do label (elementos text e tspan) e o seu container (elementos rect e svg).

2. Lista das propriedades

Propriedade	Valor	Finalidade
`map`	`Object`	Objeto descrito no item 1.1
`width`	`String`	Valor da propriedade `width` do objeto de estilo (`css`) do `div` em que está contido o elemento `svg`. O valor default é `100%`
`height`	`String`	Valor da propriedade `height` do objeto de estilo (`css`) do `div` em que está contido o elemento `svg`. O valor default é `auto`
`show-title`	`Boolean`	Indica se o título do mapa deve ser exibido. Default: `false`
`show-labels`	`Boolean`	Indica se os rótulos devem ser mostrados. Default: `false`. Se `true`, não exibe `tooltips` para os mesmos elementos, ainda que a opção `showTooltips` seja também `true`
`show-tooltips`	`Boolean`	Indica se os `tooltips` (elemento `title`) serão exibidos no evento `hover`. Caso `show-labels` também for `true`, os `tooltips` não será exibidos para o mesmo elemento em que houver um `label` sendo exibido.
`visible-paths`	`Array`	Um `array` de números correspondentes aos códigos dos `paths` que deverão ficar visíveis. Todos os demais deixarão de ser renderizados. Se fornecida uma lista vazia, todos os `paths` são renderizados.
`detach-path`	`Number`	Código do `path` a ser destacado e renderizado isoladamente. Para desabilitar a opção, basta atribuir valor `-1` à propriedade.
`grouping`	`Object`	Objeto descrito no item 1.2
`visible-groups`	`Array`	Um `array` de números correspondentes aos códigos dos grupos definidos no `grouping` que deverão ficar visíveis. Todos os demais grupos deixarão de ser renderizados. Se fornecida uma lista vazia, todos os grupos serão renderizados.
`detach-group`	`Number`	Código do grupo em `grouping` a ser destacado e renderizado isoladamente. Esse grupo passa a ocupar todo o espaço do `viewBox`. Para desabilitar a opção, basta atribuir valor `-1` à propriedade. A opção será ignorada se houver um path selecionado em `detach-path`.
`chart`	`Object`	Objecto descrito no item 1.3
`show-legend`	`Boolean`	Indica se a legenda do `chart` deve ser exibida.
`enable-group-hover`	`Boolean`	Quando `true`, os elementos `path` do grupo sofrem decréscimo da opacidade no evento `hover` em qualquer um dos `paths` do mesmo grupo. O valor default é `false`. Pode ser utilizado em conjunto com `enable-path-hover`, caso em que os dois efeitos são percebidos simultaneamente.
`enable-path-hover`	`Boolean`	Quanto `true`, o elemento `path` sofre sofre decréscimo da opacidade no evento `hover`. O valor default é `true`. Pode ser utilizado em conjunto com `enable-group-hover`, caso em que os dois efeitos são percebidos simultaneamente.