@ixnode/geo-sphere

@ixnode/geo-sphere is a powerful and flexible Node.js package for rendering interactive maps. It supports various projections (currently only Mercator projection - more are planned), languages, and advanced interactivity, allowing you to display geographical points and create a fully interactive mapping experience.

🚀 Features

• Map Display: Render world maps or other geographical maps in Mercator projection.
• Point Rendering: Display geographical points using latitude and longitude.
• Resizable: Dynamically adjust the map size to fit different screen dimensions.
• Integrated Country Database: Includes all countries with multiple resolution levels by default.
• Interactive Countries: Countries can be clicked, triggering a customizable callback function. Hover and title effects are also supported.
• Multi-language Support: Available in multiple languages: cz|de|en|es|fr|hr|it|pl|sv.
• Mouse and Touch Interaction: The map supports zooming and panning via mouse and touch gestures.
• Lightweight and built with TypeScript
• Build on top with storybook

📦 Installation

npm install @ixnode/geo-sphere

or

yarn add @ixnode/geo-sphere

🔧 Usage

Display example

Example: Germany is selected, but the mouse is hovering over Prague, Czech Republic.

Basic Usage

import React from 'react';
import { WorldMap } from '@ixnode/geo-sphere';
import '@ixnode/geo-sphere/dist/styles.css';

const App = () => (
    <WorldMap
        height={500}
        width={1000}
        country="de"
        language="en"
    />
);

export default App;

Usage with country callback function

import React from 'react';
import { WorldMap, CountryData } from '@ixnode/geo-sphere';
import '@ixnode/geo-sphere/dist/styles.css';

const App = () => (
    <WorldMap
        height={500}
        width={1000}
        country="de"
        language="en"
        dataSource="medium"
        onClickCountry={(data: CountryData) => { console.log(data); }}
    />
);

export default App;

The callback function logs something like (according to the clicked country and the given language):

{
  "id": "de",
  "name": "Germany",
  "latitude": 50.304018990688554,
  "longitude": 7.5794992771470975,
  "screenPosition": {
    "x": 401,
    "y": 333
  },
  "svgPosition": {
    "x": 843746,
    "y": 6499094
  }
}

Usage with place callback function

import React from 'react';
import { WorldMap, PlaceData } from '@ixnode/geo-sphere';
import '@ixnode/geo-sphere/dist/styles.css';

const App = () => (
    <WorldMap
        height={500}
        width={1000}
        country="de"
        language="en"
        dataSource="medium"
        onClickPlace={(data: PlaceData) => { console.log(data); }}
    />
);

export default App;

The callback function logs something like (according to the clicked country and the given language):

{
  "id": "place-berlin",
  "latitude": 52.5235,
  "longitude": 13.4115,
  "name": "Berlin",
  "population": 3662381,
  "screenPosition": {
    "x": 629,
    "y": 295 
  },
  "svgPosition": {
    "x": 1580.7000732421875,
    "y": 6909.73095703125
  }
}

🔧 Properties

Common countries (country)

Use ISO 3166-1 alpha-2 code to select a country. Examples:

See https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 for more information.

Common languages (language)

Currently supported languages:

🛠 Development

Building the Project

To build the project locally:

npm run build

Running Storybook

View and develop components in isolation:

npm run storybook

Open: http://localhost:6006/

Example: Spain is selected, but the mouse is hovering over Lisbon, Portugal.

📦 Publishing to npm

Check TypeScript Code

• Runs the TypeScript compiler to detect errors without generating any JavaScript output
• Should not throw an error

npx tsc --noEmit

Build the project

• Runs the build process to produce production-ready artifacts
• Test build for a future release process to npmjs.org
• Should not throw an error

npm run build

Verify the build

• Checks that the compiled code runs as expected
• Should not throw an error

ES Modules build

node dist/index.js

or to ignore possible warnings:

node --no-warnings dist/index.js

CommonJS build

node dist/index.cjs

Bump the version

Update the version in the package.json, e.g., from 1.0.0 to 1.0.1, to create a new release:

npm version patch

Alternatively:

• Use npm version minor for new features.
• Use npm version major for breaking changes.

Publish the package

npm publish --access public

Verify the publication

Check the package on npm: https://www.npmjs.com/package/@ixnode/geo-sphere.

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

Authors

• Björn Hempel bjoern@hempel.li - Initial work - https://github.com/bjoern-hempel

🌟 Contributing

Contributions are welcome! Feel free to submit issues or pull requests to improve this project.

🤝 Acknowledgments

Special thanks to the open-source community for providing amazing tools like React, TypeScript, and Storybook.

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog and this project adheres to Semantic Versioning.

Changelogs

[0.1.31] - 2025-01-22

• README.md changes

[0.1.30] - 2025-01-22

• Hover and click translation fix
• Add new docs images (README.md)

[0.1.29] - 2025-01-22

• General refactoring
• SVGRenderer.tsx Refactoring
• WorldMap.tsx Refactoring

[0.1.28] - 2025-01-20

• Add latitude and longitude to place hover callback function
• Add new fresh colors to country and svg map
• Map performance optimization
• Optimize lastHover triggering

[0.1.27] - 2025-01-20

• Hover fix if debug mode is enabled

[0.1.26] - 2025-01-20

• Implement country and place hover handler (onHoverCountry, onHoverPlace)

[0.1.25] - 2025-01-19

• Add new preview images

[0.1.24] - 2025-01-19

• Add priority and size to cities to optimize svg output

[0.1.23] - 2025-01-19

• Add optimized touchpad support

[0.1.22] - 2025-01-19

• Add all populations and some more translation to european capitals
• First touchpad support

[0.1.21] - 2025-01-19

• Add population and translation to some european capitals

[0.1.20] - 2025-01-19

• Add translated place names
• WorldMap Refactoring
• Add place callback function
• Update README.md
• Improve hover events (place and country)

[0.1.19] - 2025-01-18

• Optimize debug output
• Show country and city hover debug information
• Export svg styles to external scss file
• Refactoring

[0.1.18] - 2025-01-15

• Disable zoom with mouse wheel if strg not pressed
  • Add hint overlay to show user information
• SVGRenderer.tsx refactoring
  • Fix touch events
  • Fix mouse events
  • Disable Standard pointer-events
  • Delegate hover, zoom etc. to SVGRenderer.tsx
  • Optimize click and move detection
• Add coordinates and click position to click event (screen and svg)

[0.1.17] - 2025-01-14

• Add translations

[0.1.16] - 2025-01-13

• Add ctrl hint if using wheel functionality
  • With effect

[0.1.15] - 2025-01-13

• Add ctrl hint if using wheel functionality

[0.1.14] - 2025-01-12

• Export interfaces

[0.1.13] - 2025-01-12

• Update README.md documentation

[0.1.12] - 2025-01-12

• Note the given SVG aspect ratio

[0.1.11] - 2025-01-11

• Add debug and logo options
• Optimize debug output

[0.1.10] - 2025-01-11

• Upgrade typescript from 4.9.5 to 5.7.3

[0.1.9] - 2025-01-11

• Upgrade storybook to ReactJS version 18.3.1 to avoid warnings

[0.1.8] - 2025-01-11

• Add zoom in and zoom out buttons to map

[0.1.7] - 2025-01-11

• Add icon logo

[0.1.6] - 2025-01-11

• Upgrade react version from 17.0.2 to 18.3.1

[0.1.5] - 2025-01-11

• Code refactoring
• Add ixnode logo
• Add new package.json importer

[0.1.4] - 2025-01-05

• Add Versions component to show project, framework and libraries versions.

[0.1.3] - 2025-01-05

• Update packages

[0.1.2] - 2025-01-04

• Update node version

[0.1.1] - 2025-01-04

• Add .nvmrc file

[0.1.0] - 2025-01-04

• Initial release
• Add typescript 4.9.5
• Add rollup to build npmjs.com packages
• etc.

Add new version

# → Either change patch version
$ vendor/bin/version-manager --patch

# → Or change minor version
$ vendor/bin/version-manager --minor

# → Or change major version
$ vendor/bin/version-manager --major

# → Usually version changes are set in the main or master branch
$ git checkout master && git pull

# → Edit your CHANGELOG.md file
$ vi CHANGELOG.md

# → Commit your changes to your repo
$ git add CHANGELOG.md VERSION .env && git commit -m "Add version $(cat VERSION)" && git push

# → Tag your version
$ git tag -a "$(cat VERSION)" -m "Version $(cat VERSION)" && git push origin "$(cat VERSION)"