bharat-choropleth 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,121 @@
+# Changelog
+
+## 0.3.0 - 2026-09-05
+
+### Fixed
+
+- Values keyed by a feature id the state registry does not know now match. A
+  feature was keyed by its id only if the registry recognised it, and otherwise
+  fell back to its *label* — so a dataset keyed by id against geometry outside
+  the registry, such as this repo's own historical Census bundle with its
+  `in-hs-*` ids, silently rendered as "No data" on every region while looking
+  perfectly healthy. Each key a caller writes is now recorded against the
+  canonical key it addresses, and a feature is matched by exact id, exact label,
+  then either resolved through the registry. Found by building a dashboard on
+  the historical bundle.
+
+### Added
+
+- `IndiaChoropleth` warns when `loadDistricts` or `loadSubDistricts` has been a
+  different function on three renders running while the level it loads has not
+  moved. That is the signature of an inline arrow: the loaders are compared by
+  identity because a genuinely different loader must refetch, so an unstable one
+  silently refetches the level over the network on every unrelated re-render
+  while still rendering correctly. One deliberate swap does not warn.
+
+### Changed
+
+- Documented `renderInsights` as a pure render slot and pointed at `onInsight`
+  for reacting to the inspected region. Calling `setState` from `renderInsights`
+  is a state update during render; the two props carry the same payload.
+
+### Changed
+
+- The default data source now points at the `v0.3.0` boundary bundle. A release
+  pins the geometry a consumer receives, not only the renderer that draws it.
+
+### Fixed
+
+- Changing values no longer reloads the level below. Repainting means handing
+  the renderer a new `MapLayer`, and the district and sub-district loaders keyed
+  their effects on the prepared regions — which carry values — so every number
+  that moved called the loader again and blanked the level while the promise was
+  in flight. A map drilled into a state, driven by a timer or a slider, blinked
+  its districts away on every tick. The loaders now key on the geometry and id
+  accessor, the things that decide which regions exist. A real geometry change
+  still reloads.
+
+### Changed
+
+- Repainting no longer re-unpacks the topology or refits the projection. Both
+  are keyed on `states.geometry`, and the decoded features are passed into layer
+  preparation instead of being unpacked a second time. Values live on the layer,
+  not the geometry, so neither step could have changed its answer.
+
+### Added
+
+- `districtValues`, district numbers nested under the state they belong to:
+  `districtValues={{ Telangana: { Hyderabad: 90 } }}`. The nesting is what makes
+  it safe — district names repeat across states (Aurangabad, Bilaspur and
+  Hamirpur each name two) and there is no district registry to resolve a bare
+  name against. Outer keys resolve through the state registry and are checked at
+  once; inner keys match a district's name, slug or id and are checked when that
+  state's districts arrive. It overlays whichever district layer is in use,
+  including one from a caller's own `loadDistricts`, leaving districts it does
+  not name at whatever that layer returned. There is deliberately no
+  `subDistrictValues`.
+- `loadDistrictTopology` and `loadSubDistrictTopology` are exported, so fetching
+  the prepared bundles from a custom loader does not mean re-deriving their URL
+  scheme by hand. The framework-free package exports them too now.
+- `BharatChoropleth`, a zero-config component over the existing renderer:
+  `<BharatChoropleth values={{ Telangana: 82 }} />` is a working map. Keys
+  resolve through the state registry the framework-free package already used —
+  display names, slugs, LGD ids, case-insensitive and separator-free forms, `&`
+  normalized to `and`, and former names such as `Orissa` — so it accepts the
+  same spellings as `bharat-choropleth-js`. Row-shaped input is read through
+  `data` + `regionKey` + `valueKey`; `values` wins when both are given.
+- Boundary data is fetched from `dataBaseUrl` when no `geometry` is supplied, and
+  district / sub-district drill-down defaults on in that case, matching the
+  framework-free facade. Drill-down geometry is fetched once per id and reused,
+  so changing `values` repaints without refetching it.
+- Exported `BharatChoroplethProps`, the state registry (`STATES`, `resolveState`,
+  `normalizeStateKey`), `ATTRIBUTION`, `DEFAULT_DATA_BASE_URL` and `GeometryInput`,
+  matching what `bharat-choropleth-js` exports.
+- The stylesheet gained the `.bharat-choropleth__status` placeholder rules the
+  framework-free package already carried, used while boundary data loads and for
+  the message if it fails.
+
+`IndiaChoropleth` is unchanged and remains the full API — `BharatChoropleth` is
+sugar over it, and passes every one of its props except `states` straight through.
+
+### Fixed
+
+- The default data source now points at the `v0.2.0` boundary bundle. It was
+  still pinned to `v0.1.0`, which predates
+  `data/generated/current-2019-subdistricts/`, so every sub-district request
+  404'd — and because a 404 means "this district has no sub-district level", the
+  level 0.2.0 added was silently unreachable for anyone on the default
+  `dataBaseUrl`. Self-hosted deployments were unaffected.
+
+## 0.2.0
+
+- Added an optional sub-district level below districts — tehsils, taluks,
+  mandals and blocks. `loadSubDistricts` is called only after a district is
+  activated, so that geometry stays code-split the way districts already are,
+  and `subDistrictDrillDownId` / `defaultSubDistrictDrillDownId` /
+  `onSubDistrictDrillDownChange` drive it controlled or uncontrolled.
+- A `loadSubDistricts` that resolves `null` marks that district a leaf: the map
+  stays on the district view and selects it rather than opening an empty level,
+  and the district is not asked again. Omit the prop entirely and every district
+  stays a leaf, exactly as before.
+- Exported `MapLevel` and `SubDistrictLoader`.
+- **Possibly breaking for TypeScript callers:** `level` on `TooltipContext` and
+  `InsightContext` widened from `"state" | "district"` to `MapLevel`, which adds
+  `"subdistrict"`. A `switch` over it that the compiler checks for
+  exhaustiveness now needs the third case. Nothing changes at runtime for a
+  two-level map.
+
+## 0.1.0
+
+- Initial public release of the React India state and district choropleth
+  component.

package/README.md

@@ -1,8 +1,15 @@
 # `bharat-choropleth`
 
 An accessible React SVG choropleth for India state and district dashboards.
-It renders a supplied state layer, supports keyboard and pointer inspection,
-and can lazy-load district layers when a user selects a state.
+It supports keyboard and pointer inspection, and lazy-loads district layers when
+a user selects a state, then sub-district layers when a user selects a district.
+
+Two entry points, same renderer:
+
+- **`BharatChoropleth`** — map state names to numbers and you have a map. Fetches
+  boundary data for you. Start here.
+- **`IndiaChoropleth`** — the core renderer. You supply every layer, accessor and
+  piece of navigation state. Everything below the quick start uses it.
 
 ## Install
 
@@ -16,7 +23,153 @@ Import the stylesheet once in the application that mounts the map:
 import "bharat-choropleth/style.css";
 ```
 
-## Use
+## Quick start
+
+```tsx
+import { BharatChoropleth } from "bharat-choropleth";
+import "bharat-choropleth/style.css";
+
+export function Map() {
+  return (
+    <BharatChoropleth
+      values={{
+        Telangana: 82,
+        Karnataka: 74,
+        Maharashtra: 91,
+      }}
+    />
+  );
+}
+```
+
+That is the whole setup. Boundary data is fetched from the prepared bundle (this
+package still ships none), states you omit render as "no data", and clicking a
+state drills into its districts, then into that district's sub-districts.
+
+Keys are resolved through the state registry, so every spelling of a state that
+a reader might reasonably type lands on the same region — display name, slug,
+LGD id, case-insensitive, separator-free, and former names:
+
+```tsx
+<BharatChoropleth
+  values={{
+    Goa: 6,
+    "Tamil Nadu": 18,
+    tamilnadu: 18,          // separator-free
+    "Jammu & Kashmir": 2,   // & normalizes to "and"
+    Orissa: 8,              // former name → Odisha
+    "in-cs-30-goa": 6,      // LGD id
+  }}
+/>
+```
+
+A name it does not recognize is ignored with one console warning naming what you
+typed; it never throws, and the rest of the map still renders. `0` is a value,
+not missing data — only `null` or an omitted state reads as "no data".
+
+Row-shaped data works without reshaping it first:
+
+```tsx
+<BharatChoropleth
+  data={[
+    { state: "Telangana", value: 82 },
+    { state: "Karnataka", value: 74 },
+  ]}
+  regionKey="state"
+  valueKey="value"
+/>
+```
+
+`regionKey` and `valueKey` default to `"region"` and `"value"`. `values` is the
+primary API: if you pass both, `values` wins and `data` is ignored rather than
+merged.
+
+Every `IndiaChoropleth` prop except `states` passes straight through, so reaching
+for the full renderer's behaviour is a prop rather than a rewrite:
+
+```tsx
+<BharatChoropleth
+  values={values}
+  colorScale={["#eef7f5", "#075b55"]}
+  formatValue={(value) => `${value}%`}
+  renderTooltip={(context) => <MyTooltip {...context} />}
+  onSelectedChange={(region, level) => track(region, level)}
+  showLegend={false}
+/>
+```
+
+Point `dataBaseUrl` at your own copy of `data/generated` to self-host the
+boundary bundles, or pass `geometry` to supply the state layer yourself — which
+also turns drill-down off, since the district files are no longer known to sit
+beside it. Turn it back on explicitly with `districts` / `subDistricts` plus your
+own `loadDistricts` / `loadSubDistricts`.
+
+### District values
+
+`values` is state-level. District numbers nest under the state they belong to:
+
+```tsx
+<BharatChoropleth
+  values={{ Telangana: 82, Maharashtra: 91 }}
+  districtValues={{
+    Telangana: { Hyderabad: 90, "Ranga Reddy": 76 },
+    Maharashtra: { Aurangabad: 44 },
+  }}
+/>
+```
+
+The nesting is load-bearing, not decoration. District names repeat across states —
+Aurangabad, Bilaspur and Hamirpur each name a district in two — and unlike states
+there is no district registry to resolve a bare name against, so a flat map could
+not say which one you meant.
+
+Outer keys go through the state registry, so every spelling `values` accepts works
+here too, and they are checked immediately. Inner keys match a district's name,
+slug or id, case-insensitively — but they can only be checked once that state's
+districts have been fetched, so a typo there is warned about when you first drill
+into that state, not at first render.
+
+It applies to whichever district layer is in use, including one from your own
+`loadDistricts`. A district named here takes this value; one that is not keeps
+whatever the layer returned, so you can override a few and leave the rest:
+
+```tsx
+<BharatChoropleth
+  loadDistricts={myLoader}                       // supplies most districts
+  districtValues={{ Telangana: { Hyderabad: 90 } }}  // overrides one
+/>
+```
+
+There is no `subDistrictValues`. Three levels of nesting stops reading clearly,
+and sub-district naming is much less settled than district naming. Set those
+through `loadSubDistricts`, which is also how you would supply district values
+from ids rather than names:
+
+```tsx
+import { loadSubDistrictTopology, DEFAULT_DATA_BASE_URL } from "bharat-choropleth";
+
+<BharatChoropleth
+  values={values}
+  loadSubDistricts={async (districtId) => {
+    const geometry = await loadSubDistrictTopology(DEFAULT_DATA_BASE_URL, districtId);
+    if (!geometry) return null;   // this district has no sub-district level
+    return {
+      geometry,
+      getId: (feature) => String(feature.properties?.id),
+      getLabel: (feature) => String(feature.properties?.name),
+      getValue: (feature) => subDistrictValues[String(feature.properties?.id)] ?? null,
+    };
+  }}
+/>
+```
+
+`loadDistrictTopology` and `loadSubDistrictTopology` are exported so fetching the
+prepared bundles does not mean re-deriving their URL scheme by hand.
+
+## Advanced usage
+
+`IndiaChoropleth` is the core renderer and is not going anywhere — the component
+above is sugar over it. Use it directly when you own the geometry.
 
 The package intentionally contains no geographic boundary data. Provide a
 GeoJSON feature collection or TopoJSON object plus stable IDs, labels, and
@@ -56,6 +209,83 @@ selected stable state ID and returns another `MapLayer`:
 />
 ```
 
+Add `loadSubDistricts` for a third level below districts. It receives the district
+ID, the district region, and the state ID it sits in:
+
+```tsx
+<IndiaChoropleth
+  states={states}
+  loadDistricts={loadDistricts}
+  loadSubDistricts={async (districtId) => {
+    const topology = await import(`./subdistricts/${districtId}.topo.json`);
+    return {
+      geometry: { topology: topology.default, object: "subdistricts" },
+      getId: (feature) => String(feature.properties?.id),
+      getLabel: (feature) => String(feature.properties?.name),
+      getValue: (feature) => subDistrictValues[String(feature.properties?.id)] ?? null,
+    };
+  }}
+/>
+```
+
+Return `null` for a district that has no sub-district level. Not every district has
+one, and a district that returns `null` is left as a leaf — the map stays on the
+district view and selects it, rather than opening a level with nothing in it. Once a
+district has answered `null` it stops offering the level and is not asked again.
+
+Without `loadSubDistricts`, a district is a leaf and activation only selects it,
+exactly as before.
+
+The breadcrumb gains a third segment. Its back step goes up exactly one level;
+"All states" is the one-step return to the national map. Controlled usage adds
+`subDistrictDrillDownId` / `onSubDistrictDrillDownChange`, with
+`defaultSubDistrictDrillDownId` as the uncontrolled path — and because a district ID
+means nothing outside the state it came from, changing `drillDownId` clears it.
+
+## Reacting to what the reader is looking at
+
+Two props carry the same payload, and picking the wrong one is the most common
+mistake with this component:
+
+| | |
+| --- | --- |
+| `renderInsights` | A **render slot**. Called during render, must be pure, returns nodes. |
+| `onInsight` | A **callback**. Called from an effect. Set state, fire analytics, drive another panel from here. |
+
+```tsx
+// Wrong — this is a state update during render.
+<BharatChoropleth renderInsights={(context) => { setInspected(context); return null; }} />
+
+// Right.
+<BharatChoropleth onInsight={(context) => setInspected(context)} />
+```
+
+`onInspect` is the narrower version, firing for hover and keyboard focus with the
+region alone; `onInsight` adds the scope total, share and rank.
+
+## Lazy loaders must keep a stable identity
+
+`loadDistricts` and `loadSubDistricts` are compared by identity, because a
+genuinely different loader — a different boundary edition or reporting year —
+has to refetch. An inline arrow is a new function on every render, and the
+renderer cannot tell the two apart, so the level is refetched over the network
+every time anything in the parent re-renders:
+
+```tsx
+// Refetches the district topology on every render.
+<BharatChoropleth values={values} loadDistricts={async (id) => fetchDistricts(id, metric)} />
+
+// Fetches once per state, and again only when `metric` actually changes.
+const loadDistricts = useCallback(async (id) => fetchDistricts(id, metric), [metric]);
+<BharatChoropleth values={values} loadDistricts={loadDistricts} />
+```
+
+The component warns on the console when it sees a loader change three times
+running without the level below it moving, which is the signature of the mistake.
+
+If all you need is district *numbers* rather than different geometry, prefer
+[`districtValues`](#district-values) — it repaints without refetching anything.
+
 ## Features
 
 - Keyboard-accessible regions with Enter/Space activation and focus inspection.
@@ -63,9 +293,13 @@ selected stable state ID and returns another `MapLayer`:
 - Controlled or uncontrolled selection and drill-down state.
 - Optional neutral reference overlays kept outside statistical values.
 - GeoJSON and TopoJSON inputs, with `d3-geo` projection sized to the SVG.
+- `BharatChoropleth` for name-keyed values, fetched boundary data, and drill-down
+  configured for you.
 
-`IndiaChoroplethProps` and its related layer/context types are exported for
-TypeScript consumers. See the [repository](https://github.com/shashankbudem/bharat-choropleth)
+`BharatChoroplethProps`, `IndiaChoroplethProps` and the related layer/context
+types are exported for TypeScript consumers, along with the state registry
+(`STATES`, `resolveState`, `normalizeStateKey`) if you want to resolve names
+yourself. See the [repository](https://github.com/shashankbudem/bharat-choropleth)
 for the full API, examples, boundary-data attribution, and the framework-free
 [`bharat-choropleth-js`](https://www.npmjs.com/package/bharat-choropleth-js)
 package.