@maptiler/sdk 3.4.0-rc3 → 3.4.0

package/.husky/pre-commit

@@ -1,3 +1,3 @@
 npx lint-staged;
-npm run test;
-npm run docs;
+npx ts-typecheck;
+npm run test;

package/README.md

@@ -32,12 +32,7 @@ npm install --save @maptiler/sdk
 ⚠️ Please keep in mind that if you use any additional [MapTiler modules](https://docs.maptiler.com/sdk-js/modules/), you must update them to a version that supports MapTiler SDK JS v3.
 
 # API documentation
-For further documentation and examples, check out [docs.maptiler.com](https://docs.maptiler.com/sdk-js/api/). 
-
-Full api typedoc documentation can also be generated via the commands:
-
-`npm run docs:md` to generate markdown in `docs`
-`npm run docs:html` to generate html docs in `docs-html`
+In addition to the details and examples provided in this readme, check out the [complete API documentation](https://docs.maptiler.com/sdk-js/api/)
 
 # Quick start
 
@@ -160,6 +155,7 @@ The SDK hosted on our CDN is bundled as *[Universal Module Definition](https://g
     </script>
   </body>
 </html>
+
 ```
 
 Check out the minimalist code samples in the [demos](demos) directory.
@@ -545,7 +541,138 @@ map.on("terrainAnimationStop", (e) => {
   });
 });
 ```
+# Halo and Space Options
+
+The `halo` and `space` options allow for enhanced visual customization of the map, especially for globe projections.  
+
+## `halo` (Atmospheric Glow)  
+The `halo` option adds a gradient-based atmospheric glow around the globe, simulating the visual effect of Earth's atmosphere when viewed from space.  
+
+### Usage:  
+You can enable a simple halo by setting it to `true`:  
+```ts
+const map = new maptilersdk.Map({
+  container: document.getElementById("map"),
+  style: maptilersdk.MapStyle.OUTDOOR,
+  halo: true,
+});
+```
+For more customization, you can define a radial gradient with scale and stops:
+```ts
+
+const map = new maptilersdk.Map({
+  container: document.getElementById("map"),
+  style: maptilersdk.MapStyle.OUTDOOR,
+  halo: {
+    scale: 1.5, // Controls the halo size
+    stops: [
+      [0.2, "transparent"],
+      [0.2, "red"],
+      [0.4, "red"],
+      [0.4, "transparent"],
+      [0.6, "transparent"],
+      [0.6, "red"],
+      [0.8, "red"],
+      [0.8, "transparent"],
+      [1.0, "transparent"],
+    ],
+  },
+});
+```
+You can also set the halo dynamically after the map loads:
+```ts
+map.on("load", () => {
+  map.setHalo({
+    scale: 2,
+    stops: [
+      [0.0, "rgba(135,206,250,1)"],
+      [0.5, "rgba(0,0,250,0.75)"],
+      [0.75, "rgba(250,0,0,0.0)"],
+    ],
+  });
+});
+```
+## `space` (Background Environment)
 
+The space option allows customizing the background environment of the globe, simulating deep space or skybox effects.
+### Usage
+
+You can enable a simple space background with a solid color:
+```ts
+const map = new maptilersdk.Map({
+  container: document.getElementById("map"),
+  style: maptilersdk.MapStyle.OUTDOOR,
+  space: {
+    color: "#111122", // Dark space-like color
+  },
+});
+```
+Alternatively, you can provide a cubemap for a space backround using one of the following methods:
+
+#### Predefined Presets:
+
+- `space`: Dark blue hsl(210, 100%, 4%) background and white stars (transparent background image). Space color changes the background color, stars always stay white.
+- `stars` (default): Black background (image mask), space color changes the stars color, background always stays black. 
+- `milkyway`: Black half-transparent background with standard milkyway and stars. Space color changes the stars and milkyway color, background always stays black. 
+- `milkyway-subtle`: Black half-transparent background with subtle milkyway and less stars.   Space color changes the stars and milkyway color, background always stays black.Black half-transparent background with standard milkyway and stars.   Space color changes the stars and milkyway color, background always stays black.
+- `milkyway-bright`: Black half-transparent background with bright milkyway and more stars.   Space color changes the stars and milkyway color, background always stays black.
+
+```ts
+const map = new maptilersdk.Map({
+  container: document.getElementById("map"),
+  style: maptilersdk.MapStyle.OUTDOOR,
+  space: {
+    preset: "space",
+  },
+});
+```
+#### Cubemap Images (Custom Skybox):
+```ts
+const map = new maptilersdk.Map({
+  container: document.getElementById("map"),
+  style: maptilersdk.MapStyle.OUTDOOR,
+  space: {
+    faces: {
+      nX: '/path-to-image/nX.png',
+      nY: '/path-to-image/nY.png',
+      nZ: '/path-to-image/nZ.png',
+      pX: '/path-to-image/pX.png',
+      pY: '/path-to-image/pY.png',
+      pZ: '/path-to-image/pZ.png',
+    },
+  },
+});
+```
+#### Cubemap Path with image format
+
+This fetches all images from a path, this assumes all files are named px, nx, py, ny, pz, nz and suffixed with the appropriate extension specified in `format`.
+```ts
+    const map = new maptilersdk.Map({
+      container: document.getElementById("map"),
+      style: maptilersdk.MapStyle.OUTDOOR,
+      space: {
+        path: {
+          baseUrl: "spacebox/transparent",
+          format: "png", // Defaults to PNG
+        },
+      },
+    });
+```
+#### Set the space background dynamically:
+```ts
+map.on("load", () => {
+  map.setSpace({
+    color: "red",
+    path: {
+      baseUrl: "spacebox/transparent",
+    },
+  });
+});
+```
+
+Note: if `space.color` or `space.<faces | path | preset>` are not explicitly set in the call to `setSpace`, then the previous value will remain for this field.
+
+Further code examples can be found in `~/demos/`
 
 # Easy language switching
 The language generally depends on the style but we made it possible to easily set and update from a built-in list of languages.
@@ -1114,155 +1241,6 @@ Turning off *zoom compensation* allows for more accurate adjustments to the visu
 All the other options are documented on [our reference page](https://docs.maptiler.com/sdk-js/api/helpers/#heatmap) and more examples are available [here](https://docs.maptiler.com/sdk-js/examples/?q=heatmap+helper).
 
 # Other helpers
-
-## Camera routes and animations
-
-The SDK comes with several classes to help with animations, particularly route animations.
-
-See `demos/07-animated-routes.html` for examples.
-
-### 🧩 `MaptilerAnimation`
-
-MaptilerAnimation is a utility class for smoothly animating between keyframes using custom easing and playback control. It supports event-based hooks for frame updates and completion, and works well within rendering loops or UI transitions.
-
-#### 🚀 Usage
-
-```ts
-// linearly animated between values
-const animation = new MaptilerAnimation({
-  keyframes: [
-    // `props` are interpolated across the duration
-    { delta: 0, props: { lon: -7.445, } },
-    // `userData` can hold any type of custom data to pass with the keyframe
-    { delta: 0.5, userData: { mydata: "whoa!" } },
-    { delta: 1, props: { lon: -7.455 } }
-  ],
-  duration: 1000, // 1 second
-  iterations: Infinity // loop forever
-});
-
-const marker = new Marker().setLngLat(
-  new LngLat(
-    -7.449346225791231,
-    39.399728941536836,
-  )
-).addTo(map);
-
-// TimeUpdate is fired every frame
-animation.addEventListener(AnimationEventTypes.TimeUpdate, (e) => {
-  marker.setLngLat(
-    new LngLat(
-      e.props.lon,
-    39.399728941536836,
-    )
-  )
-})
-// fired when the keyframe changes
-animation.addEventListener(AnimationEventTypes.Keyframe, ({ userData }) => {
-  console.log(userData.mydata) // "whoa!"
-});
-
-animation.play();
-```
-![](images/animate-linear-trimmed.gif)
-
-```ts
-// eased between values
-const animation = new MaptilerAnimation({
-  keyframes: [
-    // `props` are interpolated across the duration
-    { delta: 0, easing: EasingFunctionName.ElasticInOut, props: { lon: -7.445, } },
-    { delta: 1, props: { lon: -7.455 } }
-  ],
-  duration: 1000, // 1 second
-  iterations: Infinity // loop forever
-});
-```
-![](images/animate-elastic-trimmed.gif)
-
-### 🗺️ `AnimatedRouteLayer`
-
-`AnimatedRouteLayer` is custom layer that animates a path or route on the map based on keyframes or GeoJSON data. It supports animated line styling and camera following, making it ideal for visualizing routes, playback tracks, or timeline-based geographic events.
-
-Note: At present, to avoid problems arising from the camera being manipulated by two animatioons at any one time, there can only ever be one instance of `AnimatedRouteLayer` on the map at any time. This API may change in the future, but at present you must remove each instance of `AnimatedRouteLayer` from the map before adding another.
-
-#### ✨ Features
-  - Animate a path using keyframes or GeoJSON data
-  - Optional animated stroke styles to indicate progress
-  - Camera movement smoothing, following along the route
-  - Configurable duration, easing, delay, and iterations via geojson properties
-  - Event-based lifecycle hooks for adaptibility.
-  - Optional manual frame advancement (e.g., for scrubbing or syncing with map events, scroll etc etc)
-
-#### 🚀 Basic Usage
-```ts
-const myGeoJSONSource = {
-  "type": "FeatureCollection",
-  "features": [
-    {
-      "type": "Feature",
-      "geometry": {
-        "type": "LineString",
-        "coordinates": [
-          [-74.0060, 40.7128],
-          [-73.9352, 40.7306],
-          [-73.9851, 40.7580]
-        ]
-      },
-      "properties": {
-        "@duration": 5000, // animation params are prepended with '@'
-        "@iterations": 3,
-        "@delay": 1000,
-        "@autoplay": true,
-        "bearing": [
-          40,
-          30,
-          10,
-          10,
-          20,
-          40,
-        ]
-      }
-    }
-  ]
-}
-
-const animatedRoute = new AnimatedRouteLayer({
-  source: {
-    // assumes that the source is already added to the map with the given layer ID
-    id: "my-geojson-source", // the name of the source
-    layerID: "route-layer", // the name of the layer
-    featureSetIndex: 0, // the index of the featureset within the geojson
-  },
-  // OR
-  keyframes: [], // an array of keyframes
-
-  duration: 5000,
-  pathStrokeAnimation: {
-    // will only be appliued to LineString GeoJSON types
-    activeColor: [0, 128, 0, 1], // color of the line that has already been traversed
-    inactiveColor: [128, 128, 128, 0.5],
-  },
-  cameraAnimation: {
-    follow: true, // should the camera follow the route?
-    pathSmoothing: {
-      resolution: 20, // the resolution of the smoothness 
-      epsilon: 10, // how much the path is simplified before smoothing
-    },
-  },
-  autoplay: true,
-});
-
-// Add to map
-map.addLayer(animatedRoute);
-
-// Playback controls
-animatedRoute.play();
-animatedRoute.pause();
-```
-
-For a full example of how to use this, look at [the example](./demos/07-animated-routes.html)
-
 ## Convert GPX and KML to GeoJSON
 In the [Polyline helper section](#polyline-layer-helper) above, we have seen that one can feed the helper directly with a path to a GPX or KML file, that is then converted under the hood client-side into a GeoJSON `FeatureCollection` object. This conversion feature is also exposed and can be used as such:
 

package/dist/eslint.mjs

@@ -0,0 +1,133 @@
+// @ts-nocheck
+
+import tseslint from "typescript-eslint";
+import eslintPluginPrettierRecommended from "eslint-plugin-prettier/recommended";
+
+export default tseslint.config(
+  // https://typescript-eslint.io/getting-started/typed-linting/
+  tseslint.configs.strictTypeChecked,
+  tseslint.configs.stylisticTypeChecked,
+  tseslint.configs.recommendedTypeChecked,
+  {
+    // forked from https://www.npmjs.com/package/eslint-plugin-restrict-imports
+    plugins: {
+      import: {
+        rules: {
+          "default-imports-only": {
+            meta: {
+              type: "suggestion",
+              docs: {},
+              schema: [
+                {
+                  bannedImport: {
+                    locations: ["filePaths"],
+                    message: "string",
+                    fixedLocation: "string",
+                  },
+                },
+              ],
+            },
+            create: function (context) {
+              const filePath = context.getFilename();
+              const options = context.options[0] || {
+                "^/(.*)": {
+                  locations: ["(.*)"],
+                },
+              };
+
+              return {
+                ImportDeclaration: (node) => {
+                  Object.entries(options).forEach(([bannedImport, config]) => {
+                    const importLocationRegex = new RegExp(bannedImport);
+
+                    if (config.ignoreTypeImports && node.importKind === "type") return;
+
+                    if (importLocationRegex.test(node.source.value)) {
+                      config.locations.forEach((fp) => {
+                        const bannedLocationRegex = new RegExp(fp);
+
+                        if (bannedLocationRegex.test(filePath)) {
+                          node.specifiers.forEach((specifier) => {
+                            if (specifier.type !== "ImportDefaultSpecifier") {
+                              context.report({
+                                // @ts-expect-error `message` seems to work with this...
+                                message: config.message ?? `Importing from '${bannedImport}' is banned in '${fp}'`,
+                                node,
+                              });
+                            }
+                          });
+                        }
+                      });
+                    }
+                  });
+                },
+              };
+            },
+          },
+        },
+      },
+    },
+    rules: {
+      "import/default-imports-only": [
+        "error",
+        {
+          "maplibre-gl$": {
+            locations: ["^(?!.*\.d\.ts$).*\.((ts|js))$"],
+            message: `Maplibre-gl uses CJS modules, only default imports are supported, named imports may fail on some setups.`,
+            ignoreTypeImports: true,
+          },
+        },
+      ],
+    },
+  },
+  {
+    languageOptions: {
+      parserOptions: {
+        projectService: true,
+        tsconfigRootDir: import.meta.dirname,
+      },
+    },
+  },
+  // https://github.com/prettier/eslint-plugin-prettier
+  eslintPluginPrettierRecommended,
+  //
+  {
+    rules: {
+      "@typescript-eslint/array-type": "off",
+      "@typescript-eslint/consistent-indexed-object-style": "warn",
+      "@typescript-eslint/consistent-type-definitions": "off",
+      "@typescript-eslint/no-base-to-string": "warn",
+      "@typescript-eslint/no-confusing-void-expression": "warn",
+      "@typescript-eslint/no-explicit-any": "warn",
+      "@typescript-eslint/no-empty-function": "warn", // this is to satisfy maplibre-gl custom layer interface
+      "@typescript-eslint/no-floating-promises": "warn",
+      "@typescript-eslint/no-inferrable-types": "off",
+      "@typescript-eslint/no-misused-promises": "warn",
+      "@typescript-eslint/no-unnecessary-boolean-literal-compare": "off",
+      "@typescript-eslint/no-unnecessary-condition": "warn",
+      "@typescript-eslint/no-unnecessary-type-arguments": "off",
+      "@typescript-eslint/no-unnecessary-type-assertion": "off",
+      "@typescript-eslint/no-unnecessary-type-parameters": "off", // as we are a lib, types serve as documentation
+      "@typescript-eslint/no-unused-vars": "warn",
+      "@typescript-eslint/no-unsafe-argument": "warn",
+      "@typescript-eslint/no-unsafe-assignment": "warn",
+      "@typescript-eslint/no-unsafe-call": "warn",
+      "@typescript-eslint/no-unsafe-enum-comparison": "off",
+      "@typescript-eslint/no-unsafe-member-access": "warn",
+      "@typescript-eslint/no-unsafe-return": "warn",
+      "@typescript-eslint/no-non-null-assertion": "warn",
+      "@typescript-eslint/non-nullable-type-assertion-style": "warn",
+      "@typescript-eslint/prefer-for-of": "off",
+      "@typescript-eslint/prefer-nullish-coalescing": "warn",
+      "@typescript-eslint/prefer-optional-chain": "off",
+      "@typescript-eslint/prefer-return-this-type": "off",
+      "@typescript-eslint/prefer-string-starts-ends-with": "warn",
+      "@typescript-eslint/restrict-plus-operands": "warn",
+      "@typescript-eslint/restrict-template-expressions": "warn",
+      "@typescript-eslint/related-getter-setter-pairs": "off",
+      "@typescript-eslint/unbound-method": "warn",
+      "@typescript-eslint/use-unknown-in-catch-callback-variable": "warn",
+    },
+  },
+  //
+);