nepal-administrative-map 0.0.0-stage → 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.0.1
+
+Initial npm release (React sister of Flutter `nepal_administrative_map`):
+
+- Interactive Canvas map: 7 provinces, 77 districts, 753 local levels
+- Bilingual English / Nepali names, labels, tooltips and numbers
+- Drill-down with animated zoom, pan/pinch/wheel, selection
+- Choropleth colour scales, legend, search, markers, protected areas
+- Typed gazetteer (`Province.gandaki`, `District.kaski`, …) and `nepal-administrative-map/core` entry
+- Bundled TopoJSON (~423 KB); MIT code + CC BY 4.0 map data

package/DATA_LICENSE.md

@@ -0,0 +1,44 @@
+# Data license
+
+The boundary data in `assets/maps/nepal.topo.json` and the region names and
+codes in `src/core/gazetteer/regions.generated.ts` are licensed under
+[Creative Commons Attribution 4.0 International (CC BY 4.0)](https://creativecommons.org/licenses/by/4.0/).
+
+The package's source code is licensed separately under the MIT License; see
+[LICENSE](LICENSE).
+
+## Source
+
+**LocalBoundaries** by Open Knowledge Foundation Nepal (OKNP),
+<https://localboundries.oknp.org/download/>, licensed under CC BY 4.0.
+Downloaded 2026-10-09 ("All Nepal (777 units)" local-level TopoJSON).
+
+This package is not affiliated with or endorsed by OKNP.
+
+## Changes made
+
+The original data was modified as follows:
+
+- **Simplified** with mapshaper (Visvalingam, weighted, 40% of points kept)
+  and re-quantized (1e5 grid).
+- **Districts and provinces rebuilt** by dissolving local-level boundaries,
+  so all three levels share identical borders. (The source's own province
+  file was not used.)
+- **Merged** the two municipalities that the source splits into separate
+  polygons (Bansagadhi, Bardiya; Binayee Tribeni, Nawalparasi East).
+- **Separated** the 22 protected-area polygons (10 protected areas lying
+  outside any local level) from the local levels.
+- **Renamed** some regions to current or common spellings, keeping the
+  source spelling as an alias: Pokhara Lekhnath → Pokhara; districts
+  Chitawan → Chitwan, Kabhrepalanchok → Kavrepalanchok, Makawanpur →
+  Makwanpur, Tanahu → Tanahun, Kapilbastu → Kapilvastu, Nawalparasi_E/W →
+  Nawalparasi East/West, Rukum_E/W → Rukum East/West.
+- **Added** stable region codes and Nepali (Devanagari) names, which are not
+  part of the source data. See the Flutter package's `tool/source/names.csv`.
+- **Removed** all source attributes; each feature carries only its code.
+
+## Attribution in apps
+
+When you ship this package's map, credit the data, for example:
+
+> Boundary data: © OKNP LocalBoundaries, CC BY 4.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Abhishek Sharma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -1,3 +1,147 @@
-# Temporary Holding Version
+# nepal-administrative-map
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm](https://img.shields.io/npm/v/nepal-administrative-map.svg)](https://www.npmjs.com/package/nepal-administrative-map)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+An interactive administrative map of Nepal for **React**: **7 provinces,
+77 districts and 753 local levels**, in **English and Nepali (नेपाली)**.
+
+Sister package to the Flutter
+[`nepal_administrative_map`](https://pub.dev/packages/nepal_administrative_map)
+pub package — same data, codes, and feature set.
+
+- **One component to start:** `<NepalMap />` — no API keys, offline, ~422 KB bundled TopoJSON
+- **Bilingual:** names, labels, tooltips, legends and numbers in English or Nepali
+- **Interactive:** zoom, pan, tap to select, hover tooltips, and animated drill-down province → district → local level
+- **Data maps:** choropleth colouring with legend, markers, and place search
+- **Typed regions:** `District.kaski`, `LocalLevel.pokhara`, stable codes for clean joins
+- **Zero runtime dependencies** besides React (peer)
+
+| Provinces in Nepali | Dark mode |
+|---|---|
+| ![Provinces coloured by area, in Nepali](assets/screenshots/provinces_nepali.jpg) | ![Province map in dark mode](assets/screenshots/provinces_dark.jpg) |
+| **Overlays and bilingual labels** | **All 77 districts** |
+| ![Protected areas, city markers and bilingual labels](assets/screenshots/overlays_bilingual.jpg) | ![Districts with English and Nepali labels](assets/screenshots/districts_bilingual.jpg) |
+| **Local levels by type** | |
+| ![Local levels coloured by type, with a tooltip](assets/screenshots/local_level_types.jpg) | |
+
+## Install
+
+```sh
+npm install nepal-administrative-map
+```
+
+## Quick start
+
+```tsx
+import { NepalMap, AdminLevel } from 'nepal-administrative-map';
+import topoUrl from 'nepal-administrative-map/assets/maps/nepal.topo.json?url';
+
+export function App() {
+  return (
+    <div style={{ height: 480 }}>
+      <NepalMap
+        mapDataUrl={topoUrl}
+        level={AdminLevel.district.id}
+        onRegionTap={(region) => console.log(region.fullName('en'))}
+      />
+    </div>
+  );
+}
+```
+
+> Pass `mapDataUrl` to the bundled TopoJSON (Vite `?url`, webpack asset modules, or copy the file into your `public/` folder). Framework-agnostic data APIs are also available from `nepal-administrative-map/core`.
+
+## Common setups
+
+```tsx
+// Provinces (default), tap to select
+<NepalMap mapDataUrl={topoUrl} />
+
+// Drill down with animated zoom: province → districts → local levels
+<NepalMap mapDataUrl={topoUrl} drillDown animationDuration={400} />
+
+// Gandaki's districts, in Nepali
+import { Province } from 'nepal-administrative-map';
+<NepalMap
+  mapDataUrl={topoUrl}
+  level="district"
+  scope={Province.gandaki}
+  language="ne"
+/>
+
+// Choropleth
+import { Choropleth, ColorScale, District, LocalizedName } from 'nepal-administrative-map';
+<NepalMap
+  mapDataUrl={topoUrl}
+  level="district"
+  choropleth={new Choropleth({
+    values: new Map([
+      [District.kathmandu, 1744240],
+      [District.lalitpur, 548401],
+    ]),
+    scale: ColorScale.sequential('#fff8e1', '#e65100'),
+    title: new LocalizedName('Population', 'जनसंख्या'),
+  })}
+/>
+
+// Controller
+import { useNepalMapController, NepalMapBreadcrumb, NepalMapSearchField } from 'nepal-administrative-map';
+
+const controller = useNepalMapController();
+<>
+  <NepalMapBreadcrumb controller={controller} />
+  <NepalMapSearchField controller={controller} />
+  <NepalMap mapDataUrl={topoUrl} controller={controller} drillDown />
+</>
+```
+
+## API overview
+
+| Export | Role |
+|---|---|
+| `NepalMap` | Main React map component |
+| `NepalMapController` / `useNepalMapController` | Select, zoom, drill, language, `toPngBlob` |
+| `NepalMapBreadcrumb` | Nepal › Province › District |
+| `NepalMapSearchField` | Autocomplete search |
+| `NepalMapLegend` | Choropleth legend (also embedded when `showLegend`) |
+| `Choropleth` / `ColorScale` | Data colouring (sequential, diverging, threshold, categorical) |
+| `Province` / `District` / `LocalLevel` / `ProtectedArea` | Typed gazetteer |
+| `Nepal.byCode` / `Nepal.search` / `NepalMapData` | Core data & geometry (also via `/core`) |
+
+## Attribution
+
+Map boundary data is **CC BY 4.0** (OKNP LocalBoundaries). See [DATA_LICENSE.md](DATA_LICENSE.md).
+The map shows attribution by default; keep it visible or credit equivalently in your UI.
+
+## Example
+
+```sh
+cd example
+npm install
+npm run dev
+```
+
+## Development
+
+```sh
+npm install
+npm run generate   # gazetteer from Flutter names.csv (optional if already generated)
+npm run build      # dist/ for npm publish
+npm run pack:check # preview tarball contents
+```
+
+## Publishing
+
+```sh
+cd nepal-administrative-map
+npm login
+npm run build
+npm publish
+```
+
+Package name: [`nepal-administrative-map`](https://www.npmjs.com/package/nepal-administrative-map) (currently unpublished). Requires Node 18+.
+
+## License
+
+MIT (code) · CC BY 4.0 (map data / names / codes)