national-metadata 0.1.7 → 0.1.8

package/README.md

@@ -190,6 +190,96 @@ Object mapping 3-digit ISO codes to size scale factors for visualization.
 countrySizeScales["USA"]; // 300
 ```
 
+## 🗺️ Maps & Geographic Data
+
+National Metadata includes comprehensive mapping data for building interactive maps in React applications. The package provides continental GeoJSON files and country-specific TopoJSON files, along with React Simple Maps components.
+
+### Quick Start with Maps
+
+```typescript
+// Import continental GeoJSON
+import { southAmerica, asia, europe } from "national-metadata/maps/continents";
+
+// Import country TopoJSON dynamically
+import { getCountryTopology } from "national-metadata/maps/countries";
+
+// Import map components
+import { ComposableMap, Geographies, Geography } from "national-metadata/maps";
+
+// Use in your React component
+function WorldMap() {
+  return (
+    <ComposableMap>
+      <Geographies geography={southAmerica}>
+        {({ geographies }) =>
+          geographies.map((geo) => (
+            <Geography key={geo.rsmKey} geography={geo} />
+          ))
+        }
+      </Geographies>
+    </ComposableMap>
+  );
+}
+```
+
+### Available Continental GeoJSON
+
+```typescript
+import {
+  africa,
+  asia,
+  europe,
+  northAmerica,
+  oceania,
+  southAmerica,
+} from "national-metadata/maps/continents";
+
+// Or import all at once
+import continents from "national-metadata/maps/continents";
+```
+
+### Country TopoJSON Files
+
+```typescript
+// Option 1: Async dynamic import (recommended)
+import { getCountryTopology } from "national-metadata/maps/countries";
+const usaTopo = await getCountryTopology("usa");
+
+// Option 2: Direct import for known countries
+import usaTopology from "national-metadata/maps/countries/usa.topo.json";
+import canTopology from "national-metadata/maps/countries/can.topo.json";
+```
+
+### React Simple Maps Components
+
+The package includes all React Simple Maps components:
+
+```typescript
+import {
+  ComposableMap,
+  Geographies,
+  Geography,
+  Graticule,
+  ZoomableGroup,
+  Sphere,
+  Marker,
+  Line,
+  Annotation,
+} from "national-metadata/maps";
+```
+
+### Documentation
+
+- **[Maps Usage Guide](./MAPS_USAGE.md)** - Complete API reference and usage patterns
+- **[Maps Examples](./MAPS_EXAMPLES.md)** - Real-world examples and migration guide
+
+### Available Country Codes
+
+The package includes TopoJSON files for 250+ countries using three-letter ISO codes:
+- `usa`, `can`, `gbr`, `deu`, `fra`, `jpn`, `chn`, `ind`, `bra`, `arg`, `aus`, and many more
+
+See the full list in the [Maps Usage Guide](./MAPS_USAGE.md).
+
 ## 🚩 Flag SVGs
 
 National Metadata now includes high-quality SVG flags for all countries! The package exports flag utilities and includes all SVG files, optimized for web applications.
@@ -1031,6 +1121,18 @@ MIT License - see LICENSE file for details.
 
 ## Changelog
 
+### v0.1.8 (Upcoming)
+
+- **NEW**: Maps integration - Continental GeoJSON and country TopoJSON files
+- **NEW**: Continental GeoJSON exports: `africa`, `asia`, `europe`, `northAmerica`, `oceania`, `southAmerica`
+- **NEW**: Country TopoJSON utilities: `getCountryTopology`, `getCountryTopologyPath`
+- **NEW**: React Simple Maps components exported via `national-metadata/maps`
+- **NEW**: 250+ country TopoJSON files accessible via three-letter ISO codes
+- **NEW**: 6 continental GeoJSON files for world map visualizations
+- **NEW**: Documentation: `MAPS_USAGE.md` and `MAPS_EXAMPLES.md`
+- **IMPROVED**: Package exports map with dedicated paths for maps data
+- **IMPROVED**: Build process to include JSON map files in distribution
+
 ### v0.1.3
 
 - **NEW**: Country metadata - Comprehensive country information with scores, slugs, and Chinese translations