bharat-choropleth 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bharat Choropleth contributors
+
+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

@@ -0,0 +1,84 @@
+# `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.
+
+## Install
+
+```bash
+npm install bharat-choropleth
+```
+
+Import the stylesheet once in the application that mounts the map:
+
+```ts
+import "bharat-choropleth/style.css";
+```
+
+## Use
+
+The package intentionally contains no geographic boundary data. Provide a
+GeoJSON feature collection or TopoJSON object plus stable IDs, labels, and
+values from your data source:
+
+```tsx
+import { IndiaChoropleth, type MapLayer } from "bharat-choropleth";
+import statesTopology from "./states.topo.json";
+
+const states: MapLayer = {
+  geometry: { topology: statesTopology, object: "states" },
+  getId: (feature) => String(feature.properties?.id),
+  getLabel: (feature) => String(feature.properties?.name),
+  getValue: (feature) => valuesByStateId[String(feature.properties?.id)] ?? null,
+};
+
+export function IndiaMap() {
+  return <IndiaChoropleth states={states} />;
+}
+```
+
+For lazy state-to-district navigation, add `loadDistricts`. It receives the
+selected stable state ID and returns another `MapLayer`:
+
+```tsx
+<IndiaChoropleth
+  states={states}
+  loadDistricts={async (stateId) => {
+    const topology = await import(`./districts/${stateId}.topo.json`);
+    return {
+      geometry: { topology: topology.default, object: "districts" },
+      getId: (feature) => String(feature.properties?.id),
+      getLabel: (feature) => String(feature.properties?.name),
+      getValue: (feature) => districtValues[String(feature.properties?.id)] ?? null,
+    };
+  }}
+/>
+```
+
+## Features
+
+- Keyboard-accessible regions with Enter/Space activation and focus inspection.
+- Tooltip, legend, breadcrumb, formatting, and insight render slots.
+- 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.
+
+`IndiaChoroplethProps` and its related layer/context types are exported for
+TypeScript consumers. 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.
+
+## Local development
+
+```bash
+pnpm build
+pnpm typecheck
+pnpm test
+```
+
+## Licence
+
+MIT. This npm package contains renderer code only. Geographic data used with
+it may have separate licence and attribution requirements.

package/dist/index.d.ts

@@ -0,0 +1,170 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { Feature, Geometry, GeoJsonProperties, FeatureCollection } from 'geojson';
+import { Topology, GeometryObject } from 'topojson-specification';
+
+/** A GeoJSON feature as consumed by the renderer. Keep properties data-provider defined. */
+type MapFeature = Feature<Geometry, GeoJsonProperties>;
+type MapFeatureCollection = FeatureCollection<Geometry, GeoJsonProperties>;
+/**
+ * A layer can be plain GeoJSON, or TopoJSON plus the named object to unpack.
+ * Boundary data intentionally remains outside this package.
+ */
+type GeometrySource = MapFeatureCollection | {
+    topology: Topology;
+    object: string | GeometryObject;
+};
+type ColorScale = readonly string[] | ((value: number | null, context: ColorContext) => string);
+interface ColorContext {
+    min: number;
+    max: number;
+    feature: MapFeature;
+    id: string;
+}
+interface MapLayer {
+    /** GeoJSON or TopoJSON data for precisely this map level. */
+    geometry: GeometrySource;
+    /** Stable ID. Use LGD codes (not display names) for India boundary data. */
+    getId: (feature: MapFeature) => string;
+    /** Human-readable text used by labels and the default tooltip. */
+    getLabel: (feature: MapFeature) => string;
+    /** Return null for intentionally missing data. */
+    getValue: (feature: MapFeature) => number | null;
+    /** Optional change/secondary metric for render slots; never rendered by default. */
+    getMeta?: (feature: MapFeature) => Record<string, unknown> | undefined;
+}
+/**
+ * Non-statistical geometry shown only on the national map, for example a
+ * reference outline or claimed area that must not inherit choropleth values.
+ * It has no value accessor by design, so it can never inherit statistical data.
+ */
+interface ReferenceOverlay {
+    geometry: GeometrySource;
+    getId: (feature: MapFeature) => string;
+    getLabel: (feature: MapFeature) => string;
+    /**
+     * Required accessible context, such as “National reference outline; hatched
+     * portions outside the statistical layer have no data.” The renderer uses it
+     * verbatim and does not infer status for the entire geometry.
+     */
+    getDescription: (feature: MapFeature) => string;
+}
+interface MapRegion {
+    id: string;
+    label: string;
+    value: number | null;
+    meta?: Record<string, unknown>;
+    feature: MapFeature;
+}
+interface TooltipContext extends MapRegion {
+    level: "state" | "district";
+    total: number;
+    share: number | null;
+    /** 1-based position among regions that have a value, highest first. Null when this region has no value. */
+    rank: number | null;
+    /** How many regions at this level have a value — the denominator for `rank`. */
+    rankedCount: number;
+}
+interface InsightContext extends TooltipContext {
+    selected: boolean;
+}
+type DistrictLoader = (stateId: string, state: MapRegion) => Promise<MapLayer>;
+/** Lazily provides non-statistical context geometry for a selected state's district map. */
+type DistrictReferenceOverlayLoader = (stateId: string, state: MapRegion) => Promise<ReferenceOverlay | null>;
+interface IndiaChoroplethProps {
+    /** State/UT layer. The library does not bundle any geographic boundaries. */
+    states: MapLayer;
+    /**
+     * Optional non-statistical national geometry, rendered as a neutral hatch.
+     * It never receives a choropleth value, click handler, selection, or drill-down.
+     */
+    referenceOverlay?: ReferenceOverlay;
+    /** Called only after a state is requested, so district geometry can be code-split. */
+    loadDistricts?: DistrictLoader;
+    /**
+     * Optional lazy non-statistical context geometry for a district view. It is
+     * keyed to the drilled state, cancelled safely on navigation, and rendered
+     * only with that state's districts.
+     */
+    loadDistrictReferenceOverlay?: DistrictReferenceOverlayLoader;
+    /** Controlled state drill-down. Use null for the state map. */
+    drillDownId?: string | null;
+    /** Initial state drill-down when uncontrolled. */
+    defaultDrillDownId?: string | null;
+    onDrillDownChange?: (stateId: string | null, state?: MapRegion) => void;
+    /** Controlled selected feature (state ID on national level; district ID when drilled in). */
+    selectedId?: string | null;
+    defaultSelectedId?: string | null;
+    /** Fires with null when a click on open sea clears the selection. */
+    onSelectedChange?: (region: MapRegion | null, level: "state" | "district") => void;
+    /** Fires for hover and keyboard focus with the same shape payload. */
+    onInspect?: (region: MapRegion | null, level: "state" | "district") => void;
+    /** Receives tooltip-ready data, including the current scope total and share. */
+    onInsight?: (context: InsightContext | null) => void;
+    /** Receives every activation before state drill-down / district selection. */
+    onRegionClick?: (region: MapRegion, level: "state" | "district") => void;
+    /**
+     * Called for a click that hit no region and was not close enough to a small
+     * one. The component also clears its own uncontrolled selection on such a
+     * click, so clicking the sea drops the selection ring.
+     */
+    onBackgroundClick?: () => void;
+    /** Colors are data-driven; strings work as an ordered low-to-high ramp. */
+    colorScale?: ColorScale;
+    /** Format both tooltip and legend values. */
+    formatValue?: (value: number) => string;
+    renderTooltip?: (context: TooltipContext) => ReactNode;
+    renderInsights?: (context: InsightContext | null) => ReactNode;
+    /**
+     * Map-level visual chrome can be independently disabled/composed.
+     *
+     * On an interactive map the legend is also a filter: each swatch highlights
+     * the regions painted in it and dulls the rest, picked again or Escape to
+     * clear. A swatch with nothing in it is inert. Set `interactive: false` for a
+     * legend that is a key and nothing more.
+     */
+    showLegend?: boolean;
+    showBreadcrumb?: boolean;
+    legendLabels?: readonly [lower: string, higher: string];
+    /** Label paired with the neutral hatch in either map-level legend. */
+    referenceOverlayLegendLabel?: string;
+    /** State IDs whose statistical fill should visually merge with the reference overlay. */
+    referenceOverlayMergeIds?: readonly string[];
+    /** Render the non-statistical reference geometry as a hatch or neutral solid fill. */
+    referenceOverlayFill?: "hatch" | "solid";
+    /** Show formatted values at region centroids. */
+    showRegionValues?: boolean;
+    /**
+     * Grow any part smaller than this (view-box units) about its own centre, so it
+     * can be seen and clicked. Off by default.
+     *
+     * An archipelago cannot be drawn to scale and still be usable: Lakshadweep's
+     * islands are one to two kilometres across and spread over 250, so even
+     * drilled into they are a few pixels each. This trades exact size for
+     * visibility, keeping every part in its true position; growth is capped so a
+     * speck never reads as a real landmass.
+     *
+     * Regions with nowhere to grow into are left at their true size regardless —
+     * Puducherry is enclaves inside Tamil Nadu, and growing them would put a
+     * Puducherry of the wrong shape in the wrong place. Those fall back to the
+     * marker dot, which is a pointer target in its own right.
+     */
+    minPartExtent?: number;
+    /**
+     * Like [minPartExtent], but applied only after a state has been drilled into.
+     * When omitted, district layers inherit minPartExtent for backward compatibility.
+     */
+    minDistrictPartExtent?: number;
+    className?: string;
+    ariaLabel?: string;
+    /** Set false where a host app provides its own keyboard focus management. */
+    interactive?: boolean;
+}
+
+/**
+ * A data-agnostic, accessible SVG India map renderer. Import `@india-choropleth/react/style.css`
+ * once in the host app; data and boundaries intentionally remain separate.
+ */
+declare function IndiaChoropleth({ states, referenceOverlay, loadDistricts, loadDistrictReferenceOverlay, drillDownId, defaultDrillDownId, onDrillDownChange, selectedId, defaultSelectedId, onSelectedChange, onInspect, onInsight, onRegionClick, onBackgroundClick, colorScale, formatValue, renderTooltip, renderInsights, showLegend, showBreadcrumb, legendLabels, referenceOverlayLegendLabel, referenceOverlayMergeIds, referenceOverlayFill, showRegionValues, minPartExtent, minDistrictPartExtent, className, ariaLabel, interactive, }: IndiaChoroplethProps): react.JSX.Element;
+
+export { type ColorContext, type ColorScale, type DistrictLoader, type DistrictReferenceOverlayLoader, type GeometrySource, IndiaChoropleth, type IndiaChoroplethProps, type InsightContext, type MapFeature, type MapFeatureCollection, type MapLayer, type MapRegion, type ReferenceOverlay, type TooltipContext };