@ogis/waymark-js 2.0.0-alpha.9 → 3.0.0-alpha

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ogis/waymark-js",
-  "version": "2.0.0-alpha.9",
+  "version": "3.0.0-alpha",
   "type": "module",
   "license": "GPL-2.0-only",
   "repository": {
@@ -23,24 +23,31 @@
     ".": {
       "import": "./dist/waymark-js.js",
       "require": "./dist/waymark-js.umd.cjs"
-    }
+    },
+    "./dist/waymark-js.css": "./dist/waymark-js.css"
   },
   "scripts": {
     "build": "vite build",
-    "dev": "vite --host"
+    "dev": "concurrently \"vite --host\" \"npm run test:watch\"",
+    "test": "vitest run",
+    "test:watch": "vitest watch"
+  },
+  "vitest": {
+    "setupFiles": "./tests/setupTests.js"
   },
   "dependencies": {
+    "@turf/bbox": "^7.3.2",
     "@turf/length": "^7.2.0",
-    "font-awesome": "^4.7.0",
-    "ionicons-npm": "^2.0.1",
+    "lodash-es": "^4.17.22",
     "maplibre-gl": "^5.7.1",
-    "pinia": "^2.1.7",
-    "vue": "^3.4.21"
+    "ulid": "^3.0.2"
   },
   "devDependencies": {
-    "@vitejs/plugin-vue": "^5.0.4",
+    "concurrently": "^9.2.1",
+    "jsdom": "^24.1.0",
     "less": "^4.2.0",
     "prettier": "^3.2.5",
-    "vite": "^6.3.5"
+    "vite": "^6.3.5",
+    "vitest": "^4.0.17"
   }
 }

package/readme.md

@@ -1,11 +1,11 @@
 # Waymark JS
 
 > [!CAUTION]
-> Waymark JS v2 is currently in alpha. Many features are not yet implemented. Please see the [To-Do list](/readme.md#to-do) for details.
+> Waymark JS v3 is currently in alpha.
 
-_Create, Edit and Share Meaningful Maps_
+Adding _meaning_ to GeoJSON.
 
-Waymark JS is a JavaScript library for creating and sharing geographical information. It is designed to be easy to use and intuitive, and is suitable for a wide range of applications due to its flexibility and customisation [options](/docs/v2/2.instances.md#map-options). Waymark JS stores data in GeoJSON format.
+Waymark JS is a JavaScript library for rendering GeoJSON data on a [OpenStreetMap](https://www.openstreetmap.org/) vector basemap.
 
 Built on the shoulders of giants:
 
@@ -26,7 +26,7 @@ npm install @ogis/waymark-js
 Then import the library and CSS in your JavaScript:
 
 ```javascript
-import { Instance } from "@ogis/waymark-js";
+import { createInstance } from "@ogis/waymark-js";
 import "@ogis/waymark-js/dist/waymark-js.css";
 ```
 
@@ -43,10 +43,11 @@ To use via CDN, include the following in your HTML:
 />
 
 <script type="module">
-  import { Instance } from "https://unpkg.com/@ogis/waymark-js/dist/waymark-js.js";
+  import { createInstance } from "https://unpkg.com/@ogis/waymark-js/dist/waymark-js.js";
 </script>
 ```
 
+<!--
 #### UMD
 
 When you can't rely on native ES modules, you can load the bundled UMD build via a classic `<script>` tag. The bundle exposes a `WaymarkJS` global with the same `Instance` class that the package exports.
@@ -69,7 +70,9 @@ When you can't rely on native ES modules, you can load the bundled UMD build via
     <div id="waymark-instance" style="height: 480px"></div>
     <script>
       window.addEventListener("DOMContentLoaded", () => {
-        const instance = new WaymarkJS.Instance();
+        const instance = new WaymarkJS.createInstance({
+          id: "waymark-instance",
+        });
       });
     </script>
   </body>
@@ -77,6 +80,7 @@ When you can't rely on native ES modules, you can load the bundled UMD build via
 ```
 
 If you're self-hosting the assets, replace the CDN URLs with your local `waymark-js.css` and `waymark-js.umd.cjs` paths.
+-->
 
 ## Usage
 
@@ -89,86 +93,98 @@ Add a container element for the Instance:
 ```
 
 > [!NOTE]
-> The element that contains the Instance must have a **height** set, either inline or via CSS.
+> Instance element must have a **height** in order to be visible.
+> If there isn't a DOM element with the given id, Waymark JS will create one for you and append it to the body (with 100% width and height).
 
 ### JavaScript
 
-Create a Waymark Instance with your configuration, then load some GeoJSON data:
+Create a Waymark Instance with your configuration, showing some GeoJSON data:
 
 ```javascript
-import { Instance } from "@ogis/waymark-js";
+import { createInstance } from "@ogis/waymark-js";
 import "@ogis/waymark-js/dist/waymark-js.css";
 
-// Create a Waymark Instance with this configuration
-const instance = new Instance({
-  // See [Map Options](docs/v2/2.instances.md#map-options) for details
-  map_options: {
-    // This is the default, so can be omitted
-    div_id: "waymark-instance",
-
-    // Passed directly to MapLibre GL JS
-    // See [MapLibre Map Options](https://maplibre.org/maplibre-gl-js/docs/API/type-aliases/MapOptions/)
-    maplibre_options: {
-      zoom: 12,
-    },
-
-    // See [Marker Types](docs/v2/2.instances.md#marker-types) for details
-    marker_types: [
+const instance = createInstance({
+  // Will console.log() all Waymark JS Events
+  // debug: true,
+
+  // Unique ID repesenting the DOM element to load the Instance into
+  // Is added to the DOM if it doesn't exist
+  id: "waymark-instance",
+
+  // MapLibre GL JS Options
+  // See [MapLibre Map Options](https://maplibre.org/maplibre-gl-js/docs/API/type-aliases/MapOptions/)
+  mapOptions: {
+    zoom: 12,
+  },
+
+  // Can pass GeoJSON here
+  geoJSON: {
+    type: "FeatureCollection",
+    features: [
       {
-        marker_title: "Pub",
-        marker_shape: "marker",
-        marker_size: "large",
-        icon_type: "icon",
-        marker_icon: "ion-beer",
-        marker_colour: "#fbfbfb",
-        icon_colour: "#754423",
+        // Set an ID here so you can access the Overlay
+        id: "pub-marker",
+        type: "Feature",
+        properties: {
+          // Waymark Properties
+          waymark: {
+            // The Title & Descrption will display when the Marker is clicked
+            title: "The Scarlet Ibis",
+            description:
+              "Great pub, great food! Especially after a Long Ride 🚴🍔🍟🍺🍺💤",
+
+            // MapLibre GL JS Layer Paint Properties
+            paint: {
+              "circle-radius": 20,
+              "circle-color": "white",
+              "circle-stroke-color": "brown",
+              "circle-stroke-width": 6,
+            },
+
+            // Marker Icons
+            icon: {
+              // <img /> and <i /> tags work well here
+              html: `<div style="font-size:32px">🍺</div>`,
+
+              // Inline SVG supported
+              // svg: `<svg />`
+
+              // Image URLs supported
+              // url: "https://...pint.png
+            },
+          },
+        },
+        geometry: {
+          type: "Point",
+          coordinates: [-128.0094, 50.6539],
+        },
       },
     ],
   },
-});
 
-// Load this GeoJSON, which contains a single "pub" Marker
-instance.loadGeoJSON({
-  type: "FeatureCollection",
-  features: [
-    {
-      type: "Feature",
-      properties: {
-        type: "pub",
-        title: "The Scarlet Ibis",
-        description:
-          "Great pub, great food! Especially after a Long Ride 🚴🍔🍟🍺🍺💤",
-        image_large_url: "https://www.waymark.dev/assets/geo/pub.jpeg",
-      },
-      geometry: {
-        type: "Point",
-        coordinates: [-128.0094, 50.6539],
-      },
-    },
-  ],
+  // This function is called when the Instance has finished loading
+  // and is passed the Instance as an argument
+  onLoad: (thisInstance) => {
+    //Get the Waymark JS Overlay for the "pub-marker" Feature
+    const pubMarker = thisInstance.geoJSONStore.getItem("pub-marker");
+
+    // Get the MapLibre GL JS Map
+    const map = thisInstance.mapLibreStore.mapLibreMap;
+
+    // Set the map view to fit the Marker (instantly)
+    map.setCenter(pubMarker.geometry.coordinates);
+    map.setZoom(12);
+  },
 });
 ```
 
+<!--
 ## Documentation
 
-1. [Start Here](docs/v2/1.index.md)
-2. [Instances](docs/v2/2.instances.md)
-
-## To-Do
-
-Alpha
-
-- [ ] Demo PAGE
-
-Later
-
-- [ ] Map Options:
-  - [ ] `map_init_basemap`
-  - [ ] `show_scale`
-  - [ ] `debug_mode`
-- [ ] Viewer Options
-- [ ] Editor Options
-- [ ] GPX/KML Import/Export
+1. [Start Here](docs/v3/1.index.md)
+2. [Instances](docs/v3/2.instances.md)
+-->
 
 ## Development
 
@@ -179,7 +195,7 @@ Later
 # Install dependencies
 npm install
 
-# Run the development server
+# Run the dev server (& tests)
 npm run dev
 
 # Build for production