ethio-map-kit 0.1.1 → 0.1.2

package/README.md

@@ -1,8 +1,8 @@
 # Ethio Map Kit
 
-Type-safe React components for an interactive Ethiopia regional SVG map.
+React components for building interactive Ethiopia map visualizations.
 
-Ethio Map Kit ships a polished Ethiopia map surface, region legend, selected-region card, service-stat card, and location list. It includes default demo data, a bundled Ethiopia regions SVG, a lightweight transparent terrain WebP, and CSS for light/dark dashboard-style layouts.
+Ethio Map Kit includes a regional Ethiopia map, smooth region selection, light/dark themes, terrain and heat layers, marker support, service stats, and TypeScript types.
 
 ## Install
 
@@ -10,13 +10,7 @@ Ethio Map Kit ships a polished Ethiopia map surface, region legend, selected-reg
 npm install ethio-map-kit
 ```
 
-React and React DOM are peer dependencies:
-
-```bash
-npm install react react-dom
-```
-
-Import the stylesheet once in your app:
+Import the stylesheet once:
 
 ```tsx
 import "ethio-map-kit/styles.css";
@@ -40,95 +34,68 @@ export function App() {
       serviceStats={defaultRegionServiceStats}
       locations={defaultLocations}
       theme="light"
-      layer="terrain"
+      layer="regions"
       showLabels
-      showMarkers
-      onRegionSelect={(selection) => {
-        console.log(selection.regionId, selection.region);
+      onRegionSelect={({ regionId, region }) => {
+        console.log(regionId, region);
       }}
     />
   );
 }
 ```
 
-You can also import from the React subpath:
+## Terrain Layer
 
 ```tsx
-import { EthiopiaMap } from "ethio-map-kit/react";
+<EthiopiaMap
+  data={defaultRegionData}
+  layer="terrain"
+  theme="dark"
+/>
 ```
 
-## Exports
+The bundled terrain image is a transparent WebP, so it works in both light and dark mode.
 
-Components:
+## Custom Data
 
-- `EthiopiaMap`
-- `EthiopiaMapSurface`
-- `EthiopiaMapProvider`
-- `EthiopiaMapRoot`
-- `EthiopiaMapLegend`
-- `EthiopiaSelectedRegionCard`
-- `EthiopiaRegionServicesCard`
-- `EthiopiaLocationsPanel`
-
-Hooks:
-
-- `useEthiopiaMap`
-- `useSelectedRegionId`
-
-Default data and map metadata:
-
-- `defaultRegionData`
-- `defaultRegionServiceStats`
-- `defaultLocations`
-- `regionPathMap`
-- `ETHIOPIA_REGION_IDS`
-- `ETHIOPIA_AUTO_TOUR_SEQUENCE`
-
-## Main Component
+```tsx
+import type { RegionRecord, RegionDatum } from "ethio-map-kit";
 
-`EthiopiaMap` is the fastest way to render a complete standalone map. It wraps `EthiopiaMapProvider` and `EthiopiaMapSurface` for you.
+const data: RegionRecord<RegionDatum> = {
+  ...defaultRegionData,
+  amhara: {
+    name: "Amhara",
+    value: 78,
+    trend: "+12%",
+    copy: "High regional index with several sample cities.",
+  },
+};
 
-```tsx
-<EthiopiaMap
-  data={regionData}
-  serviceStats={serviceStats}
-  locations={locations}
-  theme="dark"
-  layer="heat"
-  selectedRegionId={selectedRegionId}
-  onRegionSelect={setSelection}
-/>
+<EthiopiaMap data={data} />;
 ```
 
-### `EthiopiaMap` Props
+## Common Props
 
-| Prop | Type | Default | Description |
-| --- | --- | --- | --- |
-| `data` | `RegionRecord<RegionDatum>` | Required | Region data keyed by Ethiopia region ID. |
-| `serviceStats` | `RegionServiceStats` | `{}` | Per-region service statistics shown in the in-map panel and service card. |
-| `locations` | `readonly LatLngLocation[]` | `[]` | Lat/lng points for marker and location-list UI. |
-| `theme` | `"light" \| "dark"` | `"light"` | Visual theme. |
-| `layer` | `"regions" \| "heat" \| "terrain"` | `"regions"` | Main visual layer. |
-| `viewMode` | `"map" \| "bars"` | `"map"` | Standard map view or bar morph view. |
-| `selectionAnimation` | `"pulse" \| "static" \| "none" \| "outline"` | `"pulse"` | Selected-region visual treatment. |
-| `showLabels` | `boolean` | `true` | Show or hide SVG labels. |
-| `showMarkers` | `boolean` | `false` | Show or hide location markers. |
-| `showInMapStats` | `boolean` | `true` | Show selected-region stats inside the map surface. |
-| `autoTour` | `boolean` | `false` | Automatically cycle through regions. |
-| `autoTourSequence` | `readonly (EthiopiaRegionId \| null)[]` | `ETHIOPIA_AUTO_TOUR_SEQUENCE` | Custom tour route. Use `null` for reset steps. |
-| `autoTourIntervalMs` | `number` | `3200` | Delay between auto-tour steps. |
-| `regionColors` | `PartialRegionRecord<string>` | `{}` | Override choropleth color for one or more regions. |
-| `selectedRegionId` | `EthiopiaRegionId \| null` | Uncontrolled | Controlled selected region. |
-| `defaultSelectedRegionId` | `EthiopiaRegionId \| null` | `null` | Initial selected region for uncontrolled usage. |
-| `onRegionSelect` | `(selection: EthiopiaMapSelection) => void` | `undefined` | Called when the user selects or clears a region. |
-| `className` | `string` | `undefined` | Extra class for the map surface. |
-| `svgText` | `string` | Bundled SVG | Raw SVG text override. |
-| `svgUrl` | `string` | `undefined` | Fetch an SVG from a URL instead of using the bundled SVG. |
-| `terrainImageUrl` | `string` | Bundled WebP | Custom terrain image URL. |
+| Prop | Type | Description |
+| --- | --- | --- |
+| `data` | `RegionRecord<RegionDatum>` | Region values and copy keyed by region ID. |
+| `serviceStats` | `RegionServiceStats` | Optional service indicators for each region. |
+| `locations` | `LatLngLocation[]` | Optional marker/location data. |
+| `theme` | `"light" \| "dark"` | Map theme. |
+| `layer` | `"regions" \| "heat" \| "terrain"` | Active visual layer. |
+| `viewMode` | `"map" \| "bars"` | Map view or bar view. |
+| `selectionAnimation` | `"pulse" \| "static" \| "none" \| "outline"` | Selected-region animation style. |
+| `showLabels` | `boolean` | Show or hide region labels. |
+| `showMarkers` | `boolean` | Show or hide location markers. |
+| `regionColors` | `PartialRegionRecord<string>` | Override region colors. |
+| `selectedRegionId` | `EthiopiaRegionId \| null` | Controlled selected region. |
+| `defaultSelectedRegionId` | `EthiopiaRegionId \| null` | Initial selected region. |
+| `onRegionSelect` | `(selection) => void` | Called when a region is selected or cleared. |
+| `terrainImageUrl` | `string` | Custom terrain image URL. |
 
-## Composable Layout
+## Composable Components
 
-Use the provider when you want to arrange the map and panels yourself.
+For custom layouts, wrap components with `EthiopiaMapProvider`.
 
 ```tsx
 import {
@@ -143,112 +110,35 @@ import {
 
 export function Dashboard() {
   return (
-    <EthiopiaMapProvider data={defaultRegionData} theme="light" layer="regions">
-      <div className="dashboard-grid">
-        <EthiopiaMapSurface />
-        <aside>
-          <EthiopiaMapLegend maxItems={8} />
-          <EthiopiaSelectedRegionCard />
-          <EthiopiaRegionServicesCard />
-          <EthiopiaLocationsPanel />
-        </aside>
-      </div>
+    <EthiopiaMapProvider data={defaultRegionData}>
+      <EthiopiaMapSurface />
+      <EthiopiaMapLegend />
+      <EthiopiaSelectedRegionCard />
+      <EthiopiaRegionServicesCard />
+      <EthiopiaLocationsPanel />
     </EthiopiaMapProvider>
   );
 }
 ```
 
-### `EthiopiaMapProvider` Props
-
-`EthiopiaMapProvider` accepts the same data, selection, theme, layer, marker, label, service-stat, and auto-tour props as `EthiopiaMap`, except it requires `children` and does not accept `className`, `svgText`, `svgUrl`, or `terrainImageUrl`.
-
-Use this when you want shared state across multiple package components.
-
-### `EthiopiaMapSurface` Props
-
-| Prop | Type | Default | Description |
-| --- | --- | --- | --- |
-| `className` | `string` | `undefined` | Extra class for the surface wrapper. |
-| `svgText` | `string` | Bundled SVG | Raw SVG text override. |
-| `svgUrl` | `string` | `undefined` | Runtime SVG URL override. |
-| `terrainImageUrl` | `string` | Bundled WebP | Terrain raster URL override. |
-
-`EthiopiaMapSurface` reads all map behavior from `EthiopiaMapProvider`.
-
-## Panel Components
-
-### `EthiopiaMapLegend`
-
-Renders a sorted clickable legend using the current provider data.
-
-| Prop | Type | Default | Description |
-| --- | --- | --- | --- |
-| `className` | `string` | `undefined` | Extra class for the legend panel. |
-| `title` | `string` | `"Region index"` | Legend heading. |
-| `kicker` | `string` | `"Legend"` | Small label above the heading. |
-| `maxItems` | `number` | All regions | Limit visible legend rows. |
-| `onRegionClick` | `(regionId: EthiopiaRegionId) => void` | `undefined` | Called when a non-active region is clicked. |
-
-### `EthiopiaSelectedRegionCard`
-
-Shows selected-region copy, preview SVG, and summary stats.
-
-| Prop | Type | Default | Description |
-| --- | --- | --- | --- |
-| `className` | `string` | `undefined` | Extra class for the panel. |
-| `emptyTitle` | `string` | `"Click a region"` | Title shown when nothing is selected. |
-| `emptyCopy` | `string` | Built-in helper copy | Body text shown when nothing is selected. |
-| `showStats` | `boolean` | `true` | Show or hide the three summary-stat boxes. |
-| `previewSelectionAnimation` | `SelectionAnimationMode` | Provider value | Override preview animation mode. |
-| `summaryStats` | `(selection) => readonly RegionSummaryStat[]` | Built-in stats | Custom stat rows for the card. |
-| `renderPreview` | `(selection) => ReactNode` | Built-in SVG preview | Replace the selected-region preview area. |
-
-### `EthiopiaRegionServicesCard`
-
-Shows service indicators for the selected region.
-
-| Prop | Type | Default | Description |
-| --- | --- | --- | --- |
-| `className` | `string` | `undefined` | Extra class for the service panel. |
-| `emptyText` | `string` | `"Select a region to inspect service statistics."` | Empty state text. |
-
-### `EthiopiaLocationsPanel`
-
-Lists provided locations and their coordinates.
-
-| Prop | Type | Default | Description |
-| --- | --- | --- | --- |
-| `className` | `string` | `undefined` | Extra class for the locations panel. |
-| `title` | `string` | `"Locations"` | Panel heading. |
-| `kicker` | `string` | `"Lat/lng overlay"` | Small label above the heading. |
-| `showMarkerToggle` | `boolean` | `true` | Show current marker on/off state. |
-
-## Data Types
-
-### Region Data
-
-Each region must be present in the `data` object.
-
-```tsx
-import type { RegionRecord, RegionDatum } from "ethio-map-kit";
+## Exports
 
-const data: RegionRecord<RegionDatum> = {
-  amhara: {
-    name: "Amhara",
-    value: 78,
-    trend: "+12%",
-    copy: "High regional index with several sample cities.",
-    color: "#176b54",
-    summaryStats: [
-      { label: "Index", value: 78 },
-      { label: "Trend", value: "+12%" },
-    ],
-  },
-  // include the remaining EthiopiaRegionId keys...
-};
-```
+- `EthiopiaMap`
+- `EthiopiaMapProvider`
+- `EthiopiaMapSurface`
+- `EthiopiaMapLegend`
+- `EthiopiaSelectedRegionCard`
+- `EthiopiaRegionServicesCard`
+- `EthiopiaLocationsPanel`
+- `useEthiopiaMap`
+- `useSelectedRegionId`
+- `defaultRegionData`
+- `defaultRegionServiceStats`
+- `defaultLocations`
+- `ETHIOPIA_REGION_IDS`
+- `ETHIOPIA_AUTO_TOUR_SEQUENCE`
 
-Valid region IDs:
+## Region IDs
 
 ```text
 tigray
@@ -266,163 +156,3 @@ somali
 dire-dawa
 harari
 ```
-
-### Service Stats
-
-```tsx
-import type { RegionServiceStats } from "ethio-map-kit";
-
-const serviceStats: RegionServiceStats = {
-  amhara: [
-    {
-      label: "Maternal death rate",
-      valueKind: "percent",
-      value: 67,
-      comparison: {
-        enabled: true,
-        percent: 12,
-        direction: "increase",
-        period: "last month",
-        outcome: "negative",
-      },
-    },
-    {
-      label: "Hospitals",
-      valueKind: "number",
-      value: 86,
-      comparison: {
-        enabled: true,
-        percent: 5,
-        direction: "increase",
-        period: "last year",
-        outcome: "positive",
-      },
-    },
-  ],
-};
-```
-
-### Locations
-
-```tsx
-import type { LatLngLocation } from "ethio-map-kit";
-
-const locations: LatLngLocation[] = [
-  {
-    name: "Bahir Dar",
-    region: "amhara",
-    lat: 11.59,
-    lng: 37.39,
-    category: "hospital",
-    color: "#f7c948",
-    radius: 5,
-    intensity: 76,
-  },
-];
-```
-
-## Customization Examples
-
-### Controlled Selection
-
-```tsx
-const [selectedRegionId, setSelectedRegionId] =
-  useState<EthiopiaRegionId | null>(null);
-
-<EthiopiaMap
-  data={defaultRegionData}
-  selectedRegionId={selectedRegionId}
-  onRegionSelect={({ regionId }) => setSelectedRegionId(regionId)}
-/>;
-```
-
-### Custom Region Colors
-
-```tsx
-<EthiopiaMap
-  data={defaultRegionData}
-  regionColors={{
-    amhara: "#2563eb",
-    oromia: "#16a34a",
-    "addis-ababa": "#dc2626",
-  }}
-/>
-```
-
-### Custom Terrain Asset
-
-```tsx
-<EthiopiaMap
-  data={defaultRegionData}
-  layer="terrain"
-  terrainImageUrl="/assets/ethiopia-terrain.webp"
-/>
-```
-
-The bundled terrain asset is a transparent WebP so it works in both light and dark mode.
-
-### Auto Tour
-
-```tsx
-<EthiopiaMap
-  data={defaultRegionData}
-  autoTour
-  autoTourIntervalMs={4500}
-  autoTourSequence={["amhara", "oromia", "addis-ababa", null]}
-/>
-```
-
-The default route is:
-
-```text
-Afar -> Tigray -> Amhara -> Benishangul-Gumuz -> Gambela -> South West Ethiopia -> South Ethiopia -> Sidama -> Central Ethiopia -> Addis Ababa -> Dire Dawa -> Harari -> Somali -> Oromia -> reset
-```
-
-### Custom Selected-Region Preview
-
-```tsx
-<EthiopiaSelectedRegionCard
-  renderPreview={({ region }) =>
-    region ? <strong>{region.name}</strong> : <span>No region</span>
-  }
-/>
-```
-
-## Package Boundary And Source Visibility
-
-The published npm package contains compiled output from `dist` and this README. It does not publish the TypeScript source files or the original private repository structure.
-
-This is the normal model for frontend npm packages: consumers receive JavaScript, CSS, type declarations, and assets needed to run the component. The code can still be inspected by determined users after installation, even when it is compiled or minified. Minification and narrow package exports are useful for distribution and casual obfuscation, but they are not a security boundary.
-
-The same rule applies to browser deployments: any JavaScript, SVG, image, or CSS needed by a public client-side page can be downloaded by the browser. Keep sensitive business logic on a server if it must be private.
-
-## Local Development
-
-From the repository root:
-
-```bash
-npm install
-npm run dev:react
-npm run typecheck --workspace ethio-map-kit
-npm run build --workspace ethio-map-kit
-```
-
-Open the local demo at:
-
-```text
-http://localhost:5174/
-```
-
-## Publishing
-
-Before publishing a new package version:
-
-```bash
-npm run typecheck --workspace ethio-map-kit
-npm run build --workspace ethio-map-kit
-npm pack --workspace ethio-map-kit --dry-run
-npm version patch --workspace ethio-map-kit
-npm publish --workspace ethio-map-kit --access public
-```
-
-npm package versions are immutable. If `ethio-map-kit@0.1.0` has already been published, publish the next patch, minor, or major version instead of trying to overwrite it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ethio-map-kit",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Type-safe React components for an interactive Ethiopia regional SVG map.",
   "type": "module",
   "license": "MIT",