dotted-map 1.3.0 → 2.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Basile Bruneau
+
+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

@@ -26,23 +26,99 @@ npm i dotted-map
 
 ```js
 const fs = require('fs');
-const DottedMap = require('dotted-map');
+const DottedMap = require('dotted-map').default;
+// Or in the browser: import DottedMap from 'dotted-map';
 
 const map = new DottedMap({ height: 60, grid: 'diagonal' });
 
-map.addPin({ lat: 40.73061, lng: -73.935242, svgOptions: { color: '#d6ff79', radius: 0.4 } });
-map.addPin({ lat: 48.8534, lng: 2.3488, svgOptions: { color: '#fffcf2', radius: 0.4 } });
+map.addPin({
+  lat: 40.73061,
+  lng: -73.935242,
+  svgOptions: { color: '#d6ff79', radius: 0.4 },
+});
+map.addPin({
+  lat: 48.8534,
+  lng: 2.3488,
+  svgOptions: { color: '#fffcf2', radius: 0.4 },
+});
 
-const svgMap = map.getSVG({ radius: 0.22, color: '#423B38', shape: 'circle', backgroundColor: '#020300' });
+const svgMap = map.getSVG({
+  radius: 0.22,
+  color: '#423B38',
+  shape: 'circle',
+  backgroundColor: '#020300',
+});
 
 fs.writeFileSync('./map.svg', svgMap);
 ```
 
-Note: if you use a large number of points (height or width ≥ 100), it may take a bit of time to compute the map (from 1 to 30 seconds depending on your device and number of points). This is why the result grid is cached. If you don't change the parameters of `new DottedMap`, the next maps will be a lot faster to generate. You can however change the pins and the SVG options.
+If you use a large number of points (height or width ≥ 100), it may take a bit of time to compute the map (from 1 to 30 seconds depending on your device and number of points). This is why the result grid is cached. If you don’t change the parameters of `new DottedMap`, the next maps will be a lot faster to generate. You can however change the pins and the SVG options.
+
+### Precomputing the map
+
+Because the previous operation can be expansive (especially if you want to use DottedMap in a browser or React Native app), it’s possible to precompute the grid. You will still be able to add pins on-the-fly, in real time. This also allows you to import a lighter version of the library. This is especially useful if you always use the same map parameters, but only change the pins.
+
+```js
+// So you do this first step only once, when developing your app
+const getMapJSON = require('dotted-map').getMapJSON;
+
+// This function accepts the same arguments as DottedMap in the example above.
+const mapJsonString = getMapJSON({ height: 60, grid: 'diagonal' });
+console.log(mapJsonString);
+
+// This string will contain everything about the grid. You will need to copy
+// and include it in your front.
+```
+
+```js
+// Now we are in your app, let’s imagine it’s a React app
+
+// This import doesn’t include coordinates of countries: it’s lighter
+// that 'dotted-map', so especially useful in fronts.
+// However, you must give it a map you have pre-computed before.
+import DottedMap from 'dotted-map/without-countries';
+
+// Basically myMap.js contains something like:
+//
+// const MyMapString = 'the string mapJsonString that you got on the first step';
+// export default MyMapString;
+import MyMapString from './myMap';
+
+const MyComponent = () => {
+  // It’s safe to re-create the map at each render, because of the
+  // pre-computation it’s super fast ⚡️
+  const map = new DottedMap({ map: JSON.parse(MyMapString) });
+
+  map.addPin({
+    lat: 40.73061,
+    lng: -73.935242,
+    svgOptions: { color: '#d6ff79', radius: 0.4 },
+  });
+
+  const svgMap = map.getSVG({
+    radius: 0.22,
+    color: '#423B38',
+    shape: 'circle',
+    backgroundColor: '#020300',
+  });
+
+  return (
+    <div>
+      <img src={`data:image/svg+xml;utf8,${encodeURIComponent(svgMap)}`} />
+    </div>
+  );
+};
+
+export default MyComponent;
+```
+
+That’s how you can display a super stylish map in your React webapp, without impacting the size of your bundle nor the performance of your app (browsers are very fast at rendering SVGs).
 
 ## Specs
 
 ```js
+import DottedMap from 'dotted-map';
+
 // Create the map
 const map = new DottedMap({
   height,
@@ -50,7 +126,7 @@ const map = new DottedMap({
   countries: ['FRA'] // look into `countries.geo.json` to see which keys to use. You can also omit this parameter and the whole world will be used
   region: { lat: { min, max }, lng: { min, max } }, // if not present, it will fit the countries (and if no country is specified, the whole world)
   grid: 'vertical' | 'diagonal', // how points should be aligned
-  avoidOuterPins: false | true, // if it's true, prevent adding pins when they are outside of region/countries
+  avoidOuterPins: false | true, // if it’s true, prevent adding pins when they are outside of region/countries
 });
 
 // Add some points/change the color of existing points

package/index.d.ts

@@ -1,10 +1,18 @@
 namespace DottedMapLib {
-  interface Settings {
+  interface Region {
+    lat: { min: number; max: number };
+    lng: { min: number; max: number };
+  }
+
+  interface MapSettings {
     height?: number;
     width?: number;
     countries?: string[];
-    region?: { lat: { min: number; max: number }; lng: { min: number; max: number } };
+    region?: Region;
     grid?: 'vertical' | 'diagonal';
+  }
+
+  interface Settings extends MapSettings {
     avoidOuterPins?: false | true;
   }
 
@@ -30,15 +38,25 @@ namespace DottedMapLib {
   type Point = {
     x: number;
     y: number;
+    lat: number;
+    lng: number;
     data?: any;
     svgOptions?: SvgOptions;
   };
 }
 
+export const getMapJSON: (settings: DottedMapLib.MapSettings) => string;
+
 export default class DottedMap {
   constructor(settings: DottedMapLib.Settings);
 
-  addPin(pin: DottedMapLib.Pin): void;
+  addPin(pin: DottedMapLib.Pin): DottedMapLib.Point;
+  getPin(pin: DottedMapLib.Pin): DottedMapLib.Point;
   getPoints(): DottedMapLib.Point[];
   getSVG(settings: DottedMapLib.SvgSettings): string;
+  image: {
+    region: DottedMap.Region;
+    width: number;
+    height: number;
+  };
 }