@emuanalytics/flow-rdf-core 4.0.11 → 4.0.13

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { A as Annotation, M as MapStyleSpecification, S as StateStore, a as MapDataSource, b as MapLayer, F as FlowContextOptions, c as FlowContext } from './shared/flow-rdf-core.08156446.mjs';
-export { B as BackgroundLayerStyleBuilder, C as CircleLayerStyleBuilder, D as DEFAULT_CONTEXT_ID, _ as FeatureStreamOptions, s as FillExtrusionLayerStyleBuilder, q as FillLayerStyleBuilder, d as FlowCoreError, h as FlowCoreExpressionCustomFunction, i as FlowCoreExpressionCustomFunctionSignature, j as FlowCoreExpressionCustomFunctions, e as FlowCoreExpressionError, a0 as FlowCoreMap, o as FlowEngineEndpoint, f as FlowMapError, H as HeatmapLayerStyleBuilder, u as HillshadeLayerStyleBuilder, L as LineLayerStyleBuilder, T as MapAnimationOptions, U as MapCenterOptions, K as MapDataSourceOptions, N as MapDataSourceSpecification, J as MapDataSourceType, a3 as MapEvent, a2 as MapEventType, a1 as MapEventTypes, V as MapFeature, W as MapFeatureIdentifier, Z as MapFeatureStream, O as MapGeojsonData, E as MapLayerExpression, z as MapLayerOptions, I as MapLayerPropertyMetadataIndex, G as MapLayerSpecification, w as MapLayerStyleBuilder, p as MapLayerType, a6 as MapLoadingEvent, a4 as MapMouseEvent, $ as MapOptions, X as MapPaddingOptions, aa as MapPopup, a9 as MapPopupOptions, a8 as MapPopupTemplateFn, g as MapRegistry, a5 as MapSourceEvent, Y as MapSourceIdentifier, a7 as MapStyleChangeEvent, P as ParserExpression, k as ParserExpressionWithIndex, l as ParserFunctionExpression, m as ParserIndex, n as ParserProgram, aq as Path, ar as PathValue, ab as Query, ag as QueryAttribute, al as QueryDefinition, an as QueryDefinitionFn, ai as QueryExtraParams, am as QueryOptions, aj as QueryOrderClause, Q as QueryRegistry, af as QueryResultFormat, ao as QueryResultTransformFn, ak as QuerySampleOptions, ah as QueryWhereClauses, t as RasterLayerStyleBuilder, R as ReactiveExpression, au as SerializationFormat, at as StoreAnnotations, as as StoreConstructor, x as StyleExpression, r as SymbolLayerStyleBuilder, y as expr, v as layerStyle, ac as query, ad as queryMany, ae as queryOne, ap as traceReaction } from './shared/flow-rdf-core.08156446.mjs';
+import { A as Annotation, M as MapStyleSpecification, S as StateStore, a as MapDataSource, b as MapLayer, F as FlowContextOptions, c as FlowContext } from './shared/flow-rdf-core.3da5bd49.mjs';
+export { B as BackgroundLayerStyleBuilder, C as CircleLayerStyleBuilder, D as DEFAULT_CONTEXT_ID, _ as FeatureStreamOptions, s as FillExtrusionLayerStyleBuilder, q as FillLayerStyleBuilder, d as FlowCoreError, h as FlowCoreExpressionCustomFunction, i as FlowCoreExpressionCustomFunctionSignature, j as FlowCoreExpressionCustomFunctions, e as FlowCoreExpressionError, a0 as FlowCoreMap, o as FlowEngineEndpoint, f as FlowMapError, H as HeatmapLayerStyleBuilder, u as HillshadeLayerStyleBuilder, L as LineLayerStyleBuilder, T as MapAnimationOptions, U as MapCenterOptions, K as MapDataSourceOptions, N as MapDataSourceSpecification, J as MapDataSourceType, a3 as MapEvent, a2 as MapEventType, a1 as MapEventTypes, V as MapFeature, W as MapFeatureIdentifier, Z as MapFeatureStream, O as MapGeojsonData, E as MapLayerExpression, z as MapLayerOptions, I as MapLayerPropertyMetadataIndex, G as MapLayerSpecification, w as MapLayerStyleBuilder, p as MapLayerType, a6 as MapLoadingEvent, a4 as MapMouseEvent, $ as MapOptions, X as MapPaddingOptions, aa as MapPopup, a9 as MapPopupOptions, a8 as MapPopupTemplateFn, g as MapRegistry, a5 as MapSourceEvent, Y as MapSourceIdentifier, a7 as MapStyleChangeEvent, P as ParserExpression, k as ParserExpressionWithIndex, l as ParserFunctionExpression, m as ParserIndex, n as ParserProgram, aq as Path, ar as PathValue, ab as Query, ag as QueryAttribute, al as QueryDefinition, an as QueryDefinitionFn, ai as QueryExtraParams, am as QueryOptions, aj as QueryOrderClause, Q as QueryRegistry, af as QueryResultFormat, ao as QueryResultTransformFn, ak as QuerySampleOptions, ah as QueryWhereClauses, t as RasterLayerStyleBuilder, R as ReactiveExpression, au as SerializationFormat, at as StoreAnnotations, as as StoreConstructor, x as StyleExpression, r as SymbolLayerStyleBuilder, y as expr, v as layerStyle, ac as query, ad as queryMany, ae as queryOne, ap as traceReaction } from './shared/flow-rdf-core.3da5bd49.mjs';
 export { IDisposer, IObservableStream, ISubscription } from 'mobx-utils';
 export { makeAutoObservable, makeObservable } from 'mobx';
 import 'eventemitter3';

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { A as Annotation, M as MapStyleSpecification, S as StateStore, a as MapDataSource, b as MapLayer, F as FlowContextOptions, c as FlowContext } from './shared/flow-rdf-core.08156446.js';
-export { B as BackgroundLayerStyleBuilder, C as CircleLayerStyleBuilder, D as DEFAULT_CONTEXT_ID, _ as FeatureStreamOptions, s as FillExtrusionLayerStyleBuilder, q as FillLayerStyleBuilder, d as FlowCoreError, h as FlowCoreExpressionCustomFunction, i as FlowCoreExpressionCustomFunctionSignature, j as FlowCoreExpressionCustomFunctions, e as FlowCoreExpressionError, a0 as FlowCoreMap, o as FlowEngineEndpoint, f as FlowMapError, H as HeatmapLayerStyleBuilder, u as HillshadeLayerStyleBuilder, L as LineLayerStyleBuilder, T as MapAnimationOptions, U as MapCenterOptions, K as MapDataSourceOptions, N as MapDataSourceSpecification, J as MapDataSourceType, a3 as MapEvent, a2 as MapEventType, a1 as MapEventTypes, V as MapFeature, W as MapFeatureIdentifier, Z as MapFeatureStream, O as MapGeojsonData, E as MapLayerExpression, z as MapLayerOptions, I as MapLayerPropertyMetadataIndex, G as MapLayerSpecification, w as MapLayerStyleBuilder, p as MapLayerType, a6 as MapLoadingEvent, a4 as MapMouseEvent, $ as MapOptions, X as MapPaddingOptions, aa as MapPopup, a9 as MapPopupOptions, a8 as MapPopupTemplateFn, g as MapRegistry, a5 as MapSourceEvent, Y as MapSourceIdentifier, a7 as MapStyleChangeEvent, P as ParserExpression, k as ParserExpressionWithIndex, l as ParserFunctionExpression, m as ParserIndex, n as ParserProgram, aq as Path, ar as PathValue, ab as Query, ag as QueryAttribute, al as QueryDefinition, an as QueryDefinitionFn, ai as QueryExtraParams, am as QueryOptions, aj as QueryOrderClause, Q as QueryRegistry, af as QueryResultFormat, ao as QueryResultTransformFn, ak as QuerySampleOptions, ah as QueryWhereClauses, t as RasterLayerStyleBuilder, R as ReactiveExpression, au as SerializationFormat, at as StoreAnnotations, as as StoreConstructor, x as StyleExpression, r as SymbolLayerStyleBuilder, y as expr, v as layerStyle, ac as query, ad as queryMany, ae as queryOne, ap as traceReaction } from './shared/flow-rdf-core.08156446.js';
+import { A as Annotation, M as MapStyleSpecification, S as StateStore, a as MapDataSource, b as MapLayer, F as FlowContextOptions, c as FlowContext } from './shared/flow-rdf-core.3da5bd49.js';
+export { B as BackgroundLayerStyleBuilder, C as CircleLayerStyleBuilder, D as DEFAULT_CONTEXT_ID, _ as FeatureStreamOptions, s as FillExtrusionLayerStyleBuilder, q as FillLayerStyleBuilder, d as FlowCoreError, h as FlowCoreExpressionCustomFunction, i as FlowCoreExpressionCustomFunctionSignature, j as FlowCoreExpressionCustomFunctions, e as FlowCoreExpressionError, a0 as FlowCoreMap, o as FlowEngineEndpoint, f as FlowMapError, H as HeatmapLayerStyleBuilder, u as HillshadeLayerStyleBuilder, L as LineLayerStyleBuilder, T as MapAnimationOptions, U as MapCenterOptions, K as MapDataSourceOptions, N as MapDataSourceSpecification, J as MapDataSourceType, a3 as MapEvent, a2 as MapEventType, a1 as MapEventTypes, V as MapFeature, W as MapFeatureIdentifier, Z as MapFeatureStream, O as MapGeojsonData, E as MapLayerExpression, z as MapLayerOptions, I as MapLayerPropertyMetadataIndex, G as MapLayerSpecification, w as MapLayerStyleBuilder, p as MapLayerType, a6 as MapLoadingEvent, a4 as MapMouseEvent, $ as MapOptions, X as MapPaddingOptions, aa as MapPopup, a9 as MapPopupOptions, a8 as MapPopupTemplateFn, g as MapRegistry, a5 as MapSourceEvent, Y as MapSourceIdentifier, a7 as MapStyleChangeEvent, P as ParserExpression, k as ParserExpressionWithIndex, l as ParserFunctionExpression, m as ParserIndex, n as ParserProgram, aq as Path, ar as PathValue, ab as Query, ag as QueryAttribute, al as QueryDefinition, an as QueryDefinitionFn, ai as QueryExtraParams, am as QueryOptions, aj as QueryOrderClause, Q as QueryRegistry, af as QueryResultFormat, ao as QueryResultTransformFn, ak as QuerySampleOptions, ah as QueryWhereClauses, t as RasterLayerStyleBuilder, R as ReactiveExpression, au as SerializationFormat, at as StoreAnnotations, as as StoreConstructor, x as StyleExpression, r as SymbolLayerStyleBuilder, y as expr, v as layerStyle, ac as query, ad as queryMany, ae as queryOne, ap as traceReaction } from './shared/flow-rdf-core.3da5bd49.js';
 export { IDisposer, IObservableStream, ISubscription } from 'mobx-utils';
 export { makeAutoObservable, makeObservable } from 'mobx';
 import 'eventemitter3';

package/dist/lib/map/flow-core-map.mjs

@@ -313,18 +313,42 @@ const _FlowCoreMap = class _FlowCoreMap extends EventEmitter {
     return this._style.getSources(filter);
   }
   /**
-   * Register a map icon image.
-   *
-   * The image can be used on [symbol-type map layers](/flow-rdf-core/layer-reference/symbol) by specifying the image ID
-   * as the [`icon-image`](/flow-rdf-core/layer-reference/symbol#icon-image) property.
-   *
-   * @param id Image ID.
-   * @param src Image source URL.
-   * @param width Image display width.
-   * @param height Image display height.
-   * @param pixelDensity Image pixel density. Defaults to `2` - the source image should be @2x resolution to enable better quality rendering on high-resolution displays.
-   * @param recolor Set to `true` to allow recoloring of map icon image using map layer style properties.
-   */
+     * Register a map icon image.
+     *
+     * The image can be used on [symbol-type map layers](/flow-rdf-core/layer-reference/symbol) by specifying the image ID
+     * as the [`iconImage`](/flow-rdf-core/layer-reference/symbol#icon-image) property.
+     *
+     * :::warning
+     * To fully support recoloring and halo effects, the source image should be a SDF (signed distance field) image.
+     *
+     * See [MapLibre Sprite](https://maplibre.org/maplibre-style-spec/sprite/#sprite-source-format) documentation.
+     * :::
+     *
+     * @example
+     * Register and use a map icon image:
+  ```ts
+     // Register the image
+     map.registerImage('aircraft','https://flow-cdn.emu-analytics.net/centralised-airports/vehicles/aircraft.png', 50, 50, 2, true);
+  
+     // Use the image in a map layer
+     const aircraftIcons = new MapLayer({
+       id: 'aircraft_icons',
+       type: 'symbol',
+       source: 'aircraft_source',
+       style: layerStyle('symbol')
+         .iconImage('aircraft')
+         .iconColor('red')
+     });
+   ```
+     *
+     *
+     * @param id Image ID.
+     * @param src Image source URL.
+     * @param width Image display width.
+     * @param height Image display height.
+     * @param pixelDensity Image pixel density. Defaults to `2` - the source image should be @2x resolution to enable better quality rendering on high-resolution displays.
+     * @param recolor Set to `true` to allow recoloring of map icon image using map layer style properties.
+     */
   registerImage(id, src, width, height, pixelDensity = 2, recolor = false) {
     debug(`${this.formattedName}: Registering image '${id}'`);
     this._imageRegistry.registerImage(id, src, width, height, pixelDensity, recolor);

package/dist/lib/map/plugins/annotations/annotation.events.mjs

@@ -7,13 +7,22 @@ var __publicField = (obj, key, value) => {
   return value;
 };
 class AnnotationEvent extends MapEvent {
+  /**
+   * Constructs a new AnnotationEvent instance.
+   */
   constructor(type, map, data) {
     super(type, map);
+    /** Current annotation mode (`creating`, `editing`, `idle`). */
     __publicField(this, "mode");
+    /** Whether the last operation can be undo. Use this flag to enable/disable undo UI. */
     __publicField(this, "canUndo");
+    /** Whether an operation can be redone. Use this flag to enable/disable redo UI. */
     __publicField(this, "canRedo");
+    /** Currently active annotation feature ID. */
     __publicField(this, "activeFeatureId");
+    /** Currently active annotation feature type. */
     __publicField(this, "activeFeatureType");
+    /** Current set of annotation features. */
     __publicField(this, "features");
     this.mode = data.mode;
     this.canUndo = data.canUndo;

package/dist/lib/map/plugins/annotations/annotation.plugin.mjs

@@ -6,8 +6,8 @@ import turfBuffer from '@turf/buffer';
 import turfLength from '@turf/length';
 import Debug from 'debug';
 import { isPolygon, isLineString, isPoint } from '../../../utils/feature-type-checks.mjs';
-import { isNumber, isStringFull } from '../../../utils/type-checks.mjs';
 import { randomId } from '../../../utils/random-id.mjs';
+import { isNumber, isStringFull } from '../../../utils/type-checks.mjs';
 import { MapPluginBase } from '../map-plugin-base.mjs';
 import { SelectionPlugin } from '../selection/selection.plugin.mjs';
 import { addAnnotationLayers } from './annotation-layers.mjs';
@@ -24,6 +24,13 @@ var __publicField = (obj, key, value) => {
 };
 Debug("flow:annotation-plugin");
 const _AnnotationPlugin = class _AnnotationPlugin extends MapPluginBase {
+  /**
+   * Constructs a new AnnotationPlugin instance. This is called automatically when the plugin is added to a {@link FlowCoreMap} instance
+   * using {@link FlowCoreMap.usePlugin} method. {@link AnnotationPluginOptions} should be specified when calling `usePlugin`.
+   *
+   * @param pluginManager The plugin manager instance associated with the map
+   * @param options Plugin-specific options
+   */
   constructor(pluginManager, options) {
     super(pluginManager, options);
     __publicField(this, "name", "AnnotationPlugin");
@@ -44,6 +51,11 @@ const _AnnotationPlugin = class _AnnotationPlugin extends MapPluginBase {
     this.options = { ..._AnnotationPlugin._defaultOptions, ...options };
     this.options.defaultStyle = { ..._AnnotationPlugin._defaultOptions.defaultStyle, ...options?.defaultStyle };
   }
+  /**
+   * @internal
+   *
+   * Called by {@link PluginManager} when the plugin is added to the map.
+   */
   initialize() {
     this._annotationDataSource = addAnnotationLayers(this.map);
     if (this.options.selectionOptions) {
@@ -68,10 +80,20 @@ const _AnnotationPlugin = class _AnnotationPlugin extends MapPluginBase {
       });
     }
   }
+  /**
+   * @internal
+   *
+   * Called by {@link PluginManager} when the plugin is destroyed.
+   */
   destroy() {
     if (this._removeKeyboardShortcuts)
       this._removeKeyboardShortcuts();
   }
+  /**
+   * Clears all map annotations and reset the plugin state.
+   *
+   * @returns The annotation plugin instance to allow method chaining
+   */
   clear() {
     this.commit();
     this._featureIds = [];
@@ -84,6 +106,11 @@ const _AnnotationPlugin = class _AnnotationPlugin extends MapPluginBase {
     this.render();
     return this;
   }
+  /**
+   * Undoes the last operation on the operation stack and pushes it to the redo stack.
+   *
+   * @returns The annotation plugin instance to allow method chaining
+   */
   undo() {
     const operation = this._undoStack.pop();
     if (operation) {
@@ -94,7 +121,9 @@ const _AnnotationPlugin = class _AnnotationPlugin extends MapPluginBase {
     return this;
   }
   /**
-   * Redo the last undone operation.
+   * Redoes the last operation on the redo stack.
+   *
+   * @returns The annotation plugin instance to allow method chaining
    */
   redo() {
     const operation = this._redoStack.pop();
@@ -105,6 +134,11 @@ const _AnnotationPlugin = class _AnnotationPlugin extends MapPluginBase {
     }
     return this;
   }
+  /**
+   * Returns the specified annotation feature by id.
+   *
+   * @param featureId
+   */
   getFeature(featureId) {
     const feature = this._features.get(featureId);
     if (!feature) {
@@ -112,9 +146,20 @@ const _AnnotationPlugin = class _AnnotationPlugin extends MapPluginBase {
     }
     return feature;
   }
+  /**
+   * Returns all annotation features.
+   */
   getFeatures() {
     return this._featureIds.map((id) => this._features.get(id));
   }
+  /**
+   * Sets all annotation features in bulk.
+   *
+   * This operation can be undone.
+   *
+   * @param features Array of annotation features to set
+   * @returns The annotation plugin instance to allow method chaining
+   */
   setFeatures(features) {
     this.commit();
     const normalizedFeatures = features.map((f) => this.applyDefaults(f));
@@ -133,6 +178,14 @@ const _AnnotationPlugin = class _AnnotationPlugin extends MapPluginBase {
     this.performOperation(operation);
     return this;
   }
+  /**
+   * Adds an annotation feature. Note that `id` is set automatically and is available from the returned feature.
+   *
+   * This operation can be undone.
+   *
+   * @param feature The annotation feature to add
+   * @returns The added annotation feature with `id` set
+   */
   addFeature(feature) {
     this.commit();
     const fullFeature = this.applyDefaults(feature);
@@ -152,6 +205,15 @@ const _AnnotationPlugin = class _AnnotationPlugin extends MapPluginBase {
     this.performOperation(operation);
     return fullFeature;
   }
+  /**
+   * Deletes the specified annotation feature.
+   *
+   * This operation can be undone.
+   *
+   * @param featureId The id of the annotation feature to delete
+   * @returns The annotation plugin instance to allow method chaining
+   *
+   */
   deleteFeature(featureId) {
     this.commit();
     if (!featureId) {
@@ -175,6 +237,14 @@ const _AnnotationPlugin = class _AnnotationPlugin extends MapPluginBase {
     this.performOperation(operation);
     return this;
   }
+  /**
+   * Starts drawing a new annotation feature. The plugin handles subsequent mouse events to allow the user to complete the feature.
+   *
+   * Creation mode is exited when the user has completed drawing the feature or {@link AnnotationPlugin.commit} is called. Call {@link AnnotationPlugin.cancel}
+   * to programmatically exit edit mode.
+   *
+   * @param featureType The type of the feature to create
+   */
   createFeature(featureType) {
     this.commit();
     this.startDrawing();
@@ -193,6 +263,15 @@ const _AnnotationPlugin = class _AnnotationPlugin extends MapPluginBase {
       this.map.maplibreMap.off("draw.modechange", commitChanges);
     });
   }
+  /**
+   * Starts editing the specified annotation feature. The plugin handles subsequent mouse events to allow the user to move the feature
+   * and modify the feature geometry.
+   *
+   * Editing mode is exited when the user deselect the feature or {@link AnnotationPlugin.commit} is called. Call {@link AnnotationPlugin.cancel}
+   * to programmatically exit edit mode.
+   *
+   * @param featureId The id of the annotation feature to edit
+   */
   editFeature(featureId) {
     const feature = this.getFeature(featureId);
     this._mode = "editing";
@@ -222,6 +301,13 @@ const _AnnotationPlugin = class _AnnotationPlugin extends MapPluginBase {
         break;
     }
   }
+  /**
+   * Zoom the map to the specified annotation feature.
+   *
+   * @param featureId
+   * @param animationOptions
+   * @returns The annotation plugin instance to allow method chaining
+   */
   zoomToFeature(featureId, animationOptions) {
     const feature = this.getFeature(featureId);
     if (!feature)
@@ -230,6 +316,14 @@ const _AnnotationPlugin = class _AnnotationPlugin extends MapPluginBase {
     this.map.setBounds(bbox, animationOptions);
     return this;
   }
+  /**
+   * Sets a property of the specified annotation feature.
+   *
+   * @param featureId ID of annotation feature
+   * @param property Property name to set
+   * @param value Property value to set
+   * @returns The annotation plugin instance to allow method chaining
+   */
   setFeatureProperty(featureId, property, value) {
     const feature = this.getFeature(featureId);
     const featureCopy = {
@@ -239,6 +333,13 @@ const _AnnotationPlugin = class _AnnotationPlugin extends MapPluginBase {
     this._features.set(featureId, featureCopy);
     return this;
   }
+  /**
+   * Sets multiple properties of the specified annotation feature.
+   *
+   * @param featureId ID of annotation feature
+   * @param properties Map of name/value pairs
+   * @returns The annotation plugin instance to allow method chaining
+   */
   setFeatureProperties(featureId, properties) {
     const feature = this.getFeature(featureId);
     const featureCopy = {
@@ -248,6 +349,13 @@ const _AnnotationPlugin = class _AnnotationPlugin extends MapPluginBase {
     this._features.set(featureId, featureCopy);
     return this;
   }
+  /**
+   * Commits the current creation or editing operation.
+   *
+   * This operation can be undone.
+   *
+   * @returns The annotation plugin instance to allow method chaining
+   */
   commit() {
     this._onCommitCleanup.forEach((f) => f());
     this._onCommitCleanup = [];
@@ -310,6 +418,13 @@ const _AnnotationPlugin = class _AnnotationPlugin extends MapPluginBase {
     this.render();
     return this;
   }
+  /**
+   * Cancel the current creation or editing operation.
+   *
+   * This operation **cannot** be undone.
+   *
+   * @returns The annotation plugin instance to allow method chaining
+   */
   cancel() {
     this._onCommitCleanup.forEach((f) => f());
     this._onCommitCleanup = [];
@@ -325,6 +440,13 @@ const _AnnotationPlugin = class _AnnotationPlugin extends MapPluginBase {
     this.render();
     return this;
   }
+  /**
+   * Render the current state of the annotation features to the map.
+   *
+   * Note that rendering is performed automatically after creation or editing operations.
+   *
+   * @returns The annotation plugin instance to allow method chaining
+   */
   render() {
     const renderedFeatures = {
       type: "FeatureCollection",
@@ -334,6 +456,11 @@ const _AnnotationPlugin = class _AnnotationPlugin extends MapPluginBase {
     this.emitStateChange();
     return this;
   }
+  /**
+   * @internal
+   *
+   * MapPluginBase event handler
+   */
   handleDblClick(event) {
     if (!this.options.interactive) {
       return;
@@ -343,6 +470,11 @@ const _AnnotationPlugin = class _AnnotationPlugin extends MapPluginBase {
       this.editFeature(clickedFeature.id.toString());
     }
   }
+  /**
+   * @internal
+   *
+   * MapPluginBase event handler
+   */
   handleBeforeStyleChanged(event) {
     const { oldStyle, newStyle } = event;
     if (this._drawControl) {

package/dist/lib/map/plugins/data-join.plugin.mjs

@@ -16,9 +16,11 @@ const _DataJoin = class _DataJoin {
   constructor(id, map, options) {
     this.id = id;
     this.map = map;
+    __publicField(this, "options");
     __publicField(this, "autorunDisposer", null);
+    /** Reactive expression that returns array of data objects to be joined. */
     __publicField(this, "dataExpression", null);
-    __publicField(this, "options");
+    /** Parameter key/value pairs where value is a reactive expression */
     __publicField(this, "parameterExpressions", {});
     this.options = {
       ..._DataJoin.defaultOptions,
@@ -28,6 +30,10 @@ const _DataJoin = class _DataJoin {
   get source() {
     return this.options.source;
   }
+  /**
+   * Starts the reactive data join. Changes to the reactive data expression or reactive parameters will trigger new data to be obtained
+   * and joined with the map data source features.
+   */
   start() {
     this.stop();
     if (isString(this.options.data)) {
@@ -76,12 +82,16 @@ const _DataJoin = class _DataJoin {
       { name: `FlowDataJoin.${this.map.id}.${this.id})` }
     );
   }
+  /**
+   * Stops the reactive data join.
+   */
   stop() {
     if (this.autorunDisposer) {
       this.autorunDisposer();
       this.autorunDisposer = null;
     }
   }
+  /** Performs the data join given an array of data objects. */
   doDataJoin(data) {
     const source = this.map.getSource(this.options.source);
     const sourceLayer = source.type === "vector" ? this.options.sourceLayer || "geometry" : void 0;
@@ -94,6 +104,11 @@ const _DataJoin = class _DataJoin {
     }, {});
     this.map.setFeatureStateBulk({ source: source.id, sourceLayer }, featureData);
   }
+  /**
+   * Load data to join using the specified datasetId or a custom URL.
+   *
+   * Reactive parameters are added to the query as name/value querystring parameters.
+   */
   loadData(datasetOrUrl) {
     if (isURL(datasetOrUrl)) {
       const url = new URL(datasetOrUrl);
@@ -134,23 +149,44 @@ __publicField(_DataJoin, "defaultOptions", {
 });
 let DataJoin = _DataJoin;
 class DataJoinPlugin extends MapPluginBase {
+  /**
+   * Constructs a new DataJoinPlugin instance. This is called automatically when the plugin is added to a {@link FlowCoreMap} instance
+   * using {@link FlowCoreMap.usePlugin} method.
+   *
+   * @param pluginManager The plugin manager instance associated with the map
+   */
   constructor(pluginManager) {
     super(pluginManager);
     __publicField(this, "_joins", /* @__PURE__ */ new Map());
     __publicField(this, "name", "DataJoinPlugin");
   }
+  /**
+   * Add a new data join to the map using the specified options.
+   *
+   * The joined data can be accessed in map layer style expressions using the specified data join ID.
+   *
+   * @param id Data join ID
+   * @param options Data join options
+   */
   addDataJoin(id, options) {
     const dataJoin = new DataJoin(id, this.map, options);
     this._joins.set(id, dataJoin);
     dataJoin.start();
   }
+  /**
+   * @internal
+   *
+   * Used internally to set the {@link StateStore} to use for retrieving reactive properties.
+   */
   bindState(state) {
     this._joins.forEach((join) => join.start());
   }
+  /** @internal */
   destroy() {
     this._joins.forEach((join) => join.stop());
     this._joins.clear();
   }
+  /** @internal */
   handleSourceRemoved(event) {
     this._joins.forEach((join) => {
       if (join.source === event.source) {
@@ -159,6 +195,11 @@ class DataJoinPlugin extends MapPluginBase {
       }
     });
   }
+  /**
+   * Removes the specified data join from the map.
+   *
+   * @param id Data join ID
+   */
   removeDataJoin(id) {
     const dataJoin = this._joins.get(id);
     if (dataJoin) {

package/dist/lib/map/plugins/export/export.plugin.mjs

@@ -8,10 +8,24 @@ var __publicField = (obj, key, value) => {
   return value;
 };
 class ExportPlugin extends MapPluginBase {
+  /**
+   * Constructs an instance of the ExportPlugin. Note that this is called automatically
+   * when the plugin is registered with a map.
+   *
+   * @param pluginManager
+   */
   constructor(pluginManager) {
     super(pluginManager);
     __publicField(this, "name", "ExportPlugin");
   }
+  /**
+   * Export the map an image file. The map will be exported in the format specified in the options.
+   *
+   * Note that only PNG format is supported currently.
+   *
+   * @param options Export options
+   * @returns Promise that resolves to the filename of the exported map image when the export has finished
+   */
   exportMap(options) {
     const mapExporter = new MapExporter(this.map);
     return mapExporter.export(options);

package/dist/lib/map/plugins/export/map-exporter.mjs

@@ -1,7 +1,7 @@
 import maplibre from '@emuanalytics/maplibre-gl';
 import saveAs from 'file-saver';
 import { randomId } from '../../../utils/random-id.mjs';
-import { isFunction } from '../../../utils/type-checks.mjs';
+import { isFunction, isArray } from '../../../utils/type-checks.mjs';
 
 var __defProp = Object.defineProperty;
 var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
@@ -16,20 +16,20 @@ const _MapExporter = class _MapExporter {
   }
   async export(options) {
     options = { ..._MapExporter.defaultOptions, ...options };
-    const [container, mapCopy] = await this.createMapCopy(options);
+    const [container, hidden, mapCopy] = await this.createMapCopy(options);
     return new Promise((resolve, reject) => {
       const fileName = `${options.name}.${options.format}`;
       const mapCanvas = mapCopy.getCanvas();
       const exportCanvas = this.createExportCanvas(container, mapCanvas);
       const exportContext = exportCanvas.getContext("2d");
       if (!exportContext) {
-        this.destroyMapCopy(container, mapCopy);
+        this.destroyMapCopy(hidden, mapCopy);
         reject(new Error("Failed to create export canvas context"));
         return;
       }
       const drawOverlayCallback = (err) => {
         if (err) {
-          this.destroyMapCopy(container, mapCopy);
+          this.destroyMapCopy(hidden, mapCopy);
           reject(err);
         } else {
           switch (options.format) {
@@ -41,12 +41,16 @@ const _MapExporter = class _MapExporter {
             case "pdf":
               throw new Error("Export to PDF is not currently supported");
           }
-          this.destroyMapCopy(container, mapCopy);
+          this.destroyMapCopy(hidden, mapCopy);
           resolve(fileName);
         }
       };
       const mapImage = new Image();
       mapImage.onload = () => {
+        exportContext.save();
+        exportContext.fillStyle = options.background || "white";
+        exportContext.fillRect(0, 0, exportCanvas.width, exportCanvas.height);
+        exportContext.restore();
         exportContext.drawImage(mapImage, 0, 0);
         if (isFunction(options.drawOverlayFn)) {
           options.drawOverlayFn(
@@ -64,45 +68,44 @@ const _MapExporter = class _MapExporter {
     });
   }
   createMapCopy(options) {
-    const geoBounds = options.bounds || this.map.maplibreMap.getBounds().toArray().flat();
-    const geoBottomLeft = [geoBounds[0], geoBounds[1]];
-    const geoTopRight = [geoBounds[2], geoBounds[3]];
-    const geoCenter = [
-      (geoBottomLeft[0] + geoTopRight[0]) / 2,
-      (geoBottomLeft[1] + geoTopRight[1]) / 2
-    ];
-    const pxBottomLeft = this.map.maplibreMap.project(geoBottomLeft);
-    const pxTopRight = this.map.maplibreMap.project(geoTopRight);
-    const pxWidth = pxTopRight.x - pxBottomLeft.x;
-    const pxHeight = pxBottomLeft.y - pxTopRight.y;
+    let bounds = this.map.maplibreMap.getBounds();
+    let center = this.map.maplibreMap.getCenter();
+    let zoom = this.map.maplibreMap.getZoom();
+    const projection = this.map.maplibreMap.getProjection();
+    if (isArray(options.bounds) && options.bounds.length === 4 && (projection.type !== "globe" || zoom >= 4)) {
+      bounds = new maplibre.LngLatBounds(
+        [options.bounds[0], options.bounds[1]],
+        [options.bounds[2], options.bounds[3]]
+      );
+      const calculatedCamera = this.map.maplibreMap.cameraForBounds(bounds);
+      if (calculatedCamera) {
+        center = maplibre.LngLat.convert(calculatedCamera.center);
+        zoom = calculatedCamera.zoom;
+      }
+    }
     const exportWidth = options.width * options.dpmm;
     const exportHeight = options.height * options.dpmm;
-    const aspectRatios = {
-      width: pxWidth / exportWidth,
-      height: pxHeight / exportHeight
-    };
-    const coverRatio = Math.max(aspectRatios.width, aspectRatios.height);
-    const copyWidth = exportWidth * coverRatio;
-    const copyHeight = exportHeight * coverRatio;
-    const pixelRatio = exportWidth / copyWidth;
-    this.setDevicePixelRatio(pixelRatio);
+    this.setDevicePixelRatio(options.dpmm / 3.7795);
+    const hidden = document.createElement("div");
+    hidden.className = "maplibregl-export";
+    document.body.appendChild(hidden);
     const container = document.createElement("div");
-    container.id = randomId("export");
-    container.classList.add("maplibregl-export-container");
-    container.style.width = `${copyWidth}px`;
-    container.style.height = `${copyHeight}px`;
-    this.map.container.insertBefore(container, this.map.container.firstChild);
+    container.style.width = `${exportWidth}px`;
+    container.style.height = `${exportHeight}px`;
+    hidden.appendChild(container);
     const mapCopy = new maplibre.Map({
       container,
-      center: geoCenter,
-      zoom: this.map.maplibreMap.getZoom(),
+      center,
+      zoom,
       style: { ...this.map.maplibreMap.getStyle(), transition: { delay: 0, duration: 0 } },
       bearing: this.map.maplibreMap.getBearing(),
       pitch: this.map.maplibreMap.getPitch(),
       interactive: false,
       attributionControl: false,
       fadeDuration: 0,
-      preserveDrawingBuffer: true,
+      canvasContextAttributes: {
+        preserveDrawingBuffer: true
+      },
       transformRequest: this.transformMapRequest.bind(this)
     });
     mapCopy.on("styleimagemissing", (e) => this.handleMissingImage(e, mapCopy));
@@ -112,7 +115,7 @@ const _MapExporter = class _MapExporter {
           mapCopy.style.sourceCaches[sourceId]._state.stateChanges = this.map.maplibreMap.style.sourceCaches[sourceId]._state.state;
         });
         mapCopy._update();
-        setTimeout(() => resolve([container, mapCopy]), 500);
+        setTimeout(() => resolve([container, hidden, mapCopy]), 500);
       });
     });
   }