@processhub-lib/map-sdk

SDK de mapas para aplicações de agricultura de precisão. Fornece uma camada de domínio (talhões, amostras, trajetos) sobre um motor de mapa concreto hoje Leaflet sem que as telas precisem importar leaflet diretamente.

O que ele faz

• Vocabulário de domínio, não de motor de mapa. As telas trabalham com Map, Feature, Layer, Style — nunca com L.polygon, LatLngBounds ou divIcon.
• Geometrias prontas para uso. Pontos, linhas, polígonos, círculos, retângulos e GeoJSON arbitrário via factories (Feature.point, Feature.polygon, ...) e uma API fluente (map.polygon().fill(...).add()).
• Organização em camadas. Layers com visibilidade, ordem, bloqueio de edição e filtros.
• Estilos e ícones nomeados. Registre uma vez (map.styles.register, map.icons.register), referencie por string em qualquer tela.
• Seleção, desenho e edição. Multi-seleção, desenho de geometrias, edição, mover, girar, unir e dividir features.
• Medição e grade de amostragem. Área, distância e perímetro via Turf; geração de grades quadradas/hexagonais e pontos de coleta (aleatórios ou sistemáticos) dentro de um talhão.
• Undo/redo de graça. Toda mutação de domínio passa por um sistema de comandos com histórico.
• Eventos tipados (feature:click, selection:select, draw:complete, ...) e hooks React (useMap, useSelection, useFeature, ...) para integrar tudo isso a componentes.
• Motor de mapa substituível. A abstração é feita com Ports & Adapters: o domínio define a interface MapEngine; LeafletMapEngine é o adapter padrão hoje. Trocar de motor no futuro (ex.: MapLibre) significa escrever um novo adapter, não reescrever telas.

Instalação

npm install @processhub-lib/map-sdk leaflet

react e react-dom (^18.2.0) são peer dependencies, já devem existir na aplicação host. leaflet é dependency direta do pacote (é o motor usado pelo adapter padrão).

No ponto de entrada da aplicação, importe o CSS do Leaflet uma vez (o pacote não o reexporta):

import "leaflet/dist/leaflet.css";

Uso rápido

import { MapView, Feature, useMap } from "@processhub-lib/map-sdk";

function TelaTalhao({ talhaoGeoJson }: { talhaoGeoJson: GeoJSON.Geometry }) {
  return (
    <MapView
      options={{ center: { lat: -15.78, lng: -47.93 }, zoom: 13 }}
      className="h-[600px]"
    >
      <ConteudoDoMapa talhaoGeoJson={talhaoGeoJson} />
    </MapView>
  );
}

function ConteudoDoMapa({
  talhaoGeoJson,
}: {
  talhaoGeoJson: GeoJSON.Geometry;
}) {
  const map = useMap();

  useEffect(() => {
    const talhao = Feature.geojson(talhaoGeoJson, {
      style: "sample-collected",
    });
    map.add(talhao);
  }, [talhaoGeoJson]);

  return null;
}

<MapView> monta o Map (a fachada do SDK) sobre um LeafletMapEngine por padrão e o expõe via contexto React — useMap() dá acesso a essa instância dentro da árvore de filhos do MapView.

Documentação

• docs/guide/: guia de uso completo: features e layers, styles/icons/markers, seleção/desenho/medição/grade, comandos e eventos, hooks React, como trocar o motor de mapa.

Desenvolvimento do pacote

npm run typecheck:ci  # tsc --noEmit para verificar tipagem sem gerar arquivos
npm run build:ci      # vite build gera dist/index.{es,cjs}.js + .d.ts

O build usa vite-plugin-dts para gerar as declarações de tipo e não empacota react/react-dom (external, resolvidos pela aplicação host via peer dependency).