ethio-map-kit 0.1.1 → 0.1.3

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,98 @@ 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
-
-Components:
+The bundled terrain image is a transparent WebP, so it works in both light and dark mode.
 
-- `EthiopiaMap`
-- `EthiopiaMapSurface`
-- `EthiopiaMapProvider`
-- `EthiopiaMapRoot`
-- `EthiopiaMapLegend`
-- `EthiopiaSelectedRegionCard`
-- `EthiopiaRegionServicesCard`
-- `EthiopiaLocationsPanel`
-
-Hooks:
-
-- `useEthiopiaMap`
-- `useSelectedRegionId`
+## Custom Data
 
-Default data and map metadata:
+```tsx
+import type { RegionRecord, RegionDatum } from "ethio-map-kit";
 
-- `defaultRegionData`
-- `defaultRegionServiceStats`
-- `defaultLocations`
-- `regionPathMap`
-- `ETHIOPIA_REGION_IDS`
-- `ETHIOPIA_AUTO_TOUR_SEQUENCE`
+const data: RegionRecord<RegionDatum> = {
+  ...defaultRegionData,
+  amhara: {
+    name: "Amhara",
+    value: 78,
+    trend: "+12%",
+    copy: "High regional index with several sample cities.",
+  },
+};
 
-## Main Component
+<EthiopiaMap data={data} />;
+```
 
-`EthiopiaMap` is the fastest way to render a complete standalone map. It wraps `EthiopiaMapProvider` and `EthiopiaMapSurface` for you.
+## Common Props
+
+| 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. |
+| `showInMapStats` | `boolean` | Show or hide the selected region service overlay inside the map surface. |
+| `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. |
+| `className` | `string` | Class applied to the map surface in the all-in-one `EthiopiaMap`. |
+| `style` | `React.CSSProperties` | Inline style applied to the map surface in the all-in-one `EthiopiaMap`. Useful for height and width. |
+| `terrainImageUrl` | `string` | Custom terrain image URL. |
+
+## Sizing The Map
+
+The map surface fills its own container and has a default minimum height. Use `className`, `style`, or your layout wrapper to control the rendered size.
 
 ```tsx
 <EthiopiaMap
-  data={regionData}
-  serviceStats={serviceStats}
-  locations={locations}
-  theme="dark"
-  layer="heat"
-  selectedRegionId={selectedRegionId}
-  onRegionSelect={setSelection}
+  data={defaultRegionData}
+  serviceStats={defaultRegionServiceStats}
+  className="w-full"
+  style={{ width: "100%", height: 640, minHeight: 640 }}
 />
 ```
 
-### `EthiopiaMap` 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. |
-
-## Composable Layout
-
-Use the provider when you want to arrange the map and panels yourself.
+With composable components, size `EthiopiaMapSurface` directly:
+
+```tsx
+<EthiopiaMapProvider data={defaultRegionData}>
+  <div className="grid gap-4 lg:grid-cols-[minmax(0,1fr)_320px]">
+    <EthiopiaMapSurface
+      className="w-full"
+      style={{ height: 620, minHeight: 620 }}
+    />
+    <EthiopiaSelectedRegionCard />
+  </div>
+</EthiopiaMapProvider>
+```
+
+## Composable Components
+
+For custom layouts, wrap components with `EthiopiaMapProvider`.
 
 ```tsx
 import {
@@ -137,292 +134,143 @@ import {
   EthiopiaMapLegend,
   EthiopiaSelectedRegionCard,
   EthiopiaRegionServicesCard,
+  EthiopiaRegionServicesPanel,
   EthiopiaLocationsPanel,
   defaultRegionData,
+  defaultRegionServiceStats,
 } from "ethio-map-kit";
 
 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}
+      serviceStats={defaultRegionServiceStats}
+    >
+      <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";
-
-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...
-};
-```
-
-Valid region IDs:
+## Service Stats Layouts
 
-```text
-tigray
-afar
-amhara
-benishangul-gumuz
-gambela
-south-west-ethiopia
-central-ethiopia
-sidama
-south-ethiopia
-oromia
-addis-ababa
-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",
-      },
-    },
-  ],
-};
-```
+Service stats can appear inside the map surface, outside the map, or in a standalone details page. Use either the in-map overlay or the external card unless you intentionally want both.
 
-### Locations
+In-map overlay only:
 
 ```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,
-  },
-];
+<EthiopiaMapProvider
+  data={defaultRegionData}
+  serviceStats={defaultRegionServiceStats}
+  showInMapStats
+>
+  <EthiopiaMapSurface />
+  <EthiopiaSelectedRegionCard />
+</EthiopiaMapProvider>
 ```
 
-## Customization Examples
-
-### Controlled Selection
+External service card only:
 
 ```tsx
-const [selectedRegionId, setSelectedRegionId] =
-  useState<EthiopiaRegionId | null>(null);
-
-<EthiopiaMap
+<EthiopiaMapProvider
   data={defaultRegionData}
-  selectedRegionId={selectedRegionId}
-  onRegionSelect={({ regionId }) => setSelectedRegionId(regionId)}
-/>;
+  serviceStats={defaultRegionServiceStats}
+  showInMapStats={false}
+>
+  <div className="grid gap-4 lg:grid-cols-[minmax(0,1fr)_320px]">
+    <EthiopiaMapSurface className="w-full" style={{ height: 620 }} />
+    <EthiopiaRegionServicesCard />
+  </div>
+</EthiopiaMapProvider>
 ```
 
-### Custom Region Colors
+Customize the in-map overlay and its scroll list from `EthiopiaMapSurface`:
 
 ```tsx
-<EthiopiaMap
-  data={defaultRegionData}
-  regionColors={{
-    amhara: "#2563eb",
-    oromia: "#16a34a",
-    "addis-ababa": "#dc2626",
-  }}
+<EthiopiaMapSurface
+  inMapStatsClassName="my-map-stats"
+  inMapStatsStyle={{ maxHeight: 320 }}
+  inMapStatsListClassName="my-map-stats-list"
+  inMapStatsListStyle={{ maxHeight: 240 }}
 />
 ```
 
-### Custom Terrain Asset
+Opt in to incremental row rendering when a region has many indicators:
 
 ```tsx
-<EthiopiaMap
-  data={defaultRegionData}
-  layer="terrain"
-  terrainImageUrl="/assets/ethiopia-terrain.webp"
+<EthiopiaRegionServicesCard
+  incrementalRows={{
+    enabled: true,
+    initialCount: 8,
+    step: 8,
+  }}
 />
 ```
 
-The bundled terrain asset is a transparent WebP so it works in both light and dark mode.
-
-### Auto Tour
+The same option works on the in-map overlay:
 
 ```tsx
-<EthiopiaMap
-  data={defaultRegionData}
-  autoTour
-  autoTourIntervalMs={4500}
-  autoTourSequence={["amhara", "oromia", "addis-ababa", null]}
+<EthiopiaMapSurface
+  incrementalRows={{
+    enabled: true,
+    initialCount: 8,
+    step: 8,
+    thresholdPx: 80,
+  }}
 />
 ```
 
-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
+For server-rendered detail pages, fetch data in your app and pass it directly to the context-free panel. The package does not include Prisma, Next.js caching, route generation, ISR, or database fetching.
 
 ```tsx
-<EthiopiaSelectedRegionCard
-  renderPreview={({ region }) =>
-    region ? <strong>{region.name}</strong> : <span>No region</span>
-  }
-/>
+const services = await getCachedMapsData("afar", 2021, true);
+
+return (
+  <EthiopiaRegionServicesPanel
+    regionName="Afar"
+    regionValue={34}
+    services={services.afar ?? []}
+  />
+);
 ```
 
-## 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:
+## Exports
 
-```bash
-npm install
-npm run dev:react
-npm run typecheck --workspace ethio-map-kit
-npm run build --workspace ethio-map-kit
-```
+- `EthiopiaMap`
+- `EthiopiaMapProvider`
+- `EthiopiaMapSurface`
+- `EthiopiaMapLegend`
+- `EthiopiaSelectedRegionCard`
+- `EthiopiaRegionServicesCard`
+- `EthiopiaRegionServicesPanel`
+- `EthiopiaLocationsPanel`
+- `useEthiopiaMap`
+- `useSelectedRegionId`
+- `defaultRegionData`
+- `defaultRegionServiceStats`
+- `defaultLocations`
+- `ETHIOPIA_REGION_IDS`
+- `ETHIOPIA_AUTO_TOUR_SEQUENCE`
 
-Open the local demo at:
+## Region IDs
 
 ```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
+tigray
+afar
+amhara
+benishangul-gumuz
+gambela
+south-west-ethiopia
+central-ethiopia
+sidama
+south-ethiopia
+oromia
+addis-ababa
+somali
+dire-dawa
+harari
 ```
-
-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/dist/components/EthiopiaMap.d.ts

@@ -1,10 +1,18 @@
-import type { EthiopiaMapProps, EthiopiaRegionId } from "../types";
+import { type CSSProperties } from "react";
+import type { EthiopiaMapProps, EthiopiaRegionId, EthiopiaServiceRowsIncrementalConfig } from "../types";
 export interface EthiopiaMapSurfaceProps {
     className?: string;
+    style?: CSSProperties;
     svgText?: string;
     svgUrl?: string;
     terrainImageUrl?: string;
+    inMapStatsClassName?: string;
+    inMapStatsStyle?: CSSProperties;
+    inMapStatsListClassName?: string;
+    inMapStatsListStyle?: CSSProperties;
+    inMapStatsEmptyText?: string;
+    incrementalRows?: EthiopiaServiceRowsIncrementalConfig;
 }
-export declare function EthiopiaMapSurface({ className, svgText, svgUrl, terrainImageUrl, }: EthiopiaMapSurfaceProps): import("react").JSX.Element;
-export declare function EthiopiaMap({ className, svgText, svgUrl, terrainImageUrl, ...providerProps }: EthiopiaMapProps): import("react").JSX.Element;
+export declare function EthiopiaMapSurface({ className, style, svgText, svgUrl, terrainImageUrl, inMapStatsClassName, inMapStatsStyle, inMapStatsListClassName, inMapStatsListStyle, inMapStatsEmptyText, incrementalRows, }: EthiopiaMapSurfaceProps): import("react").JSX.Element;
+export declare function EthiopiaMap({ className, style, svgText, svgUrl, terrainImageUrl, inMapStatsClassName, inMapStatsStyle, inMapStatsListClassName, inMapStatsListStyle, inMapStatsEmptyText, incrementalRows, ...providerProps }: EthiopiaMapProps): import("react").JSX.Element;
 export declare function useSelectedRegionId(): EthiopiaRegionId | null;

package/dist/components/EthiopiaRegionServicesCard.d.ts

@@ -1,5 +1,11 @@
+import type { CSSProperties } from "react";
+import type { EthiopiaServiceRowsIncrementalConfig } from "../types";
 export interface EthiopiaRegionServicesCardProps {
     className?: string;
+    style?: CSSProperties;
+    listClassName?: string;
+    listStyle?: CSSProperties;
     emptyText?: string;
+    incrementalRows?: EthiopiaServiceRowsIncrementalConfig;
 }
-export declare function EthiopiaRegionServicesCard({ className, emptyText, }: EthiopiaRegionServicesCardProps): import("react").JSX.Element;
+export declare function EthiopiaRegionServicesCard({ className, style, listClassName, listStyle, emptyText, incrementalRows, }: EthiopiaRegionServicesCardProps): import("react").JSX.Element;

package/dist/components/EthiopiaRegionServicesPanel.d.ts

@@ -0,0 +1,20 @@
+import { type CSSProperties } from "react";
+import type { EthiopiaServiceRowsIncrementalConfig, ServiceStat } from "../types";
+type ServicesPanelVariant = "card" | "overlay";
+export interface EthiopiaRegionServicesPanelProps {
+    className?: string;
+    style?: CSSProperties;
+    listClassName?: string;
+    listStyle?: CSSProperties;
+    title?: string;
+    kicker?: string;
+    regionName?: string | null;
+    regionValue?: number | null;
+    services?: readonly ServiceStat[];
+    emptyText?: string;
+    variant?: ServicesPanelVariant;
+    incrementalRows?: EthiopiaServiceRowsIncrementalConfig;
+    getBarPercent?: (stat: ServiceStat) => number;
+}
+export declare function EthiopiaRegionServicesPanel({ className, style, listClassName, listStyle, title, kicker, regionName, regionValue, services, emptyText, variant, incrementalRows, getBarPercent, }: EthiopiaRegionServicesPanelProps): import("react").JSX.Element;
+export {};