indeksmaps

v1.0.0

Published

21 days ago

`indeksmaps` adalah library React + TypeScript untuk merender peta vektor interaktif Indonesia secara kustom menggunakan SVG murni.

0High
0Medium
0Low

wiicaan

IndeksMaps 🗺️

indeksmaps adalah library React + TypeScript untuk merender peta vektor interaktif Indonesia secara kustom menggunakan SVG murni.

Library ini dirancang dengan zero-external GIS dependencies (tanpa Leaflet, OpenLayers, D3, atau Mapbox), menjadikannya sangat ringan (hanya berukuran ~9 KB setelah di-build), responsif, dan mudah dikustomisasi secara visual maupun interaktif.

Fitur Utama

⚡ Ringan & Cepat: Merender peta langsung dari GeoJSON Anda menggunakan path SVG asli.
📐 Flat Linear Projection: Konversi koordinat bumi (Longitude/Latitude) ke piksel layar secara otomatis tanpa library matematika rumit.
🎛️ Zooming & Panning: Navigasi geser (drag) dan scroll-wheel zoom yang presisi terpusat ke arah kursor kursor (opsional).
🏷️ Labels Centroid Layer: Menampilkan nama wilayah secara otomatis di titik tengah wilayah dengan bayangan kontras tinggi.
🎨 Kustomisasi Pewarnaan:
- Gradasi Otomatis (Choropleth): Mewarnai wilayah berdasarkan rentang statistik numerik.
- Custom Inline Color: Mewarnai provinsi/kota tertentu secara manual melalui properti fill atau color langsung dari berkas GeoJSON.

🔗 Dua Arah & Multi-Select: Mendukung event click/hover callback dan seleksi banyak wilayah sekaligus (selectedFeatures).
💬 Kustom Tooltip: Pop-up info melayang yang posisinya mengikuti kursor mouse.

Pemasangan (Installation)

1. Instalasi Lokal (Development)

Di dalam direktori library ini:

npm link

Di dalam direktori proyek React Anda yang lain:

npm link indeksmaps

2. Instalasi via NPM (Setelah Dipublikasikan)

npm install indeksmaps

Cara Penggunaan

1. Single-Select & Tooltip Dasar

import { useState } from "react";
import { IndeksMap, GeoJSONFeature } from "indeksmaps";

function BasicMap({ geojsonData }) {
  const [selected, setSelected] = useState<GeoJSONFeature | null>(null);

  return (
    <div style={{ width: "800px", height: "500px" }}>
      <IndeksMap
        data={geojsonData}
        selectedFeature={selected}
        onFeatureClick={(f) => setSelected(f)}
        showLabels={true}
        labelField="NAME_1"
        labelColor="#ffffff"
        renderTooltip={(f) => (
          <div>
            <strong>{f.properties.NAME_1}</strong>
            <span>Kode Pos: {f.properties.postalCode}</span>
          </div>
        )}
      />
    </div>
  );
}

2. Multi-Select (Memilih Lebih dari Satu Wilayah)

import { useState } from "react";
import { IndeksMap, GeoJSONFeature } from "indeksmaps";

function MultiSelectMap({ geojsonData }) {
  const [selectedList, setSelectedList] = useState<GeoJSONFeature[]>([]);

  const handleFeatureClick = (clicked: GeoJSONFeature) => {
    const clickedId = clicked.properties.GID_1 || clicked.properties.code;
    setSelectedList((prev) => {
      const exists = prev.some((f) => (f.properties.GID_1 || f.properties.code) === clickedId);
      if (exists) {
        return prev.filter((f) => (f.properties.GID_1 || f.properties.code) !== clickedId);
      } else {
        return [...prev, clicked];
      }
    });
  };

  return (
    <IndeksMap
      data={geojsonData}
      selectedFeatures={selectedList}
      onFeatureClick={handleFeatureClick}
    />
  );
}

API Reference (Props)

Integrasi CDN jsDelivr

jsDelivr adalah CDN publik gratis yang secara otomatis mencerminkan (mirror) berkas dari NPM registry dan GitHub. Anda tidak perlu melakukan "push" langsung ke server jsDelivr.

Metode A: Pencerminan via NPM (Direkomendasikan)

Setelah Anda mempublikasikan library ke NPM menggunakan npm publish, berkas build Anda otomatis tersedia di jsDelivr.

Format URL jsDelivr untuk NPM:

https://cdn.jsdelivr.net/npm/{nama_package}@{versi}/{path_berkas}

Contoh memuat script modul ES:

https://cdn.jsdelivr.net/npm/[email protected]/dist/indeksmaps.es.js

Metode B: Pencerminan via GitHub

Jika Anda ingin menyajikan data statis (seperti berkas GeoJSON atau berkas PMTiles peta Indonesia) langsung dari repositori GitHub tanpa mempublikasikannya ke NPM:

Format URL jsDelivr untuk GitHub:

https://cdn.jsdelivr.net/gh/{username}/{nama_repo}@{branch_atau_tag}/{path_berkas}

Contoh memuat berkas PMTiles Level 1:

https://cdn.jsdelivr.net/gh/QueenOfMagician/geomaps_indo@main/data-static-indonesia/geo-indonesia/IDN_level_1.pmtiles

Contoh memuat kode wilayah Kemendagri provinces.json:

https://cdn.jsdelivr.net/gh/QueenOfMagician/geomaps_indo@main/data-static-indonesia/kode-wilayah/provinces.json