@emuanalytics/flow-rdf-core 4.0.11 → 4.0.13

package/dist/lib/map/plugins/index.d.mts

@@ -1,5 +1,5 @@
-import { a3 as MapEvent, a0 as FlowCoreMap, Y as MapSourceIdentifier, av as MapFeatureId, aw as MapPluginBase, ax as PluginManager, a5 as MapSourceEvent, a4 as MapMouseEvent, Z as MapFeatureStream, ay as PartialBy, T as MapAnimationOptions, a7 as MapStyleChangeEvent, M as MapStyleSpecification, S as StateStore, a9 as MapPopupOptions, aa as MapPopup, W as MapFeatureIdentifier } from '../../../shared/flow-rdf-core.08156446.mjs';
-export { aC as EventHandlers, aB as PluginConstructor, aA as PluginEventsType, az as PluginOptionsType } from '../../../shared/flow-rdf-core.08156446.mjs';
+import { a3 as MapEvent, a0 as FlowCoreMap, Y as MapSourceIdentifier, av as MapFeatureId, aw as MapPluginBase, ax as PluginManager, a5 as MapSourceEvent, a4 as MapMouseEvent, Z as MapFeatureStream, ay as PartialBy, T as MapAnimationOptions, a7 as MapStyleChangeEvent, M as MapStyleSpecification, S as StateStore, a9 as MapPopupOptions, aa as MapPopup, W as MapFeatureIdentifier } from '../../../shared/flow-rdf-core.3da5bd49.mjs';
+export { aC as EventHandlers, aB as PluginConstructor, aA as PluginEventsType, az as PluginOptionsType } from '../../../shared/flow-rdf-core.3da5bd49.mjs';
 import { F as Func } from '../../../shared/flow-rdf-core.63162669.mjs';
 import 'eventemitter3';
 import 'lit-html';
@@ -7,8 +7,13 @@ import '@emuanalytics/flow-engine-client';
 import 'mobx-utils';
 import '@emuanalytics/maplibre-gl';
 
+/** Annotation mode. */
 type AnnotationMode = 'creating' | 'editing' | 'idle';
+/** Type of annotation feature. */
 type AnnotationFeatureType = 'Polygon' | 'Circle' | 'LineString' | 'Point';
+/**
+ * Style properties for an annotation feature. A default style can by configured when calling {@link FlowCoreMap.usePlugin}.
+ */
 interface AnnotationStyle {
     labelSize: number;
     labelColor: string;
@@ -26,41 +31,71 @@ interface AnnotationStyle {
     selectionWidth: number;
     hoverStrokeColor: string;
 }
+/**
+ * Properties common to all annotation features.
+ */
 interface AnnotationFeatureProps extends AnnotationStyle {
+    /** Unique ID for the annotation */
     id: string;
     name: string;
     type: AnnotationFeatureType;
     selected: boolean;
     visible: boolean;
     labelText: string;
+    /** Additional properties */
     [extras: string]: any;
 }
-interface AnnotationsServiceConfig {
-    style: AnnotationStyle;
-}
+/** A map annotation as a GeoJSON feature. */
 type AnnotationFeature = GeoJSON.Feature<GeoJSON.Geometry, Partial<AnnotationFeatureProps>> & {
     id: string;
 };
 
+/** Event types emitted by the {@link AnnotationPlugin} */
 interface AnnotationEventTypes {
     annotationStateChanged: (event: AnnotationEvent) => void;
 }
+/** Names of event types emitted by the {@link AnnotationPlugin} */
 type AnnotationEventType = keyof AnnotationEventTypes;
+/**
+ * Event data associated with an {@link AnnotationPlugin} event.
+ *
+ * :::info
+ * The active feature is the feature currently being created or edited (if any).
+ * :::
+ */
 interface AnnotationEventData {
+    /** Current set of annotation features. */
     features: AnnotationFeature[];
+    /** Current annotation mode. */
     mode: AnnotationMode;
+    /** Whether the last operation can be undo. Use this flag to enable/disable undo UI. */
     canUndo: boolean;
+    /** Whether an operation can be redone. Use this flag to enable/disable redo UI. */
     canRedo: boolean;
+    /** Currently active annotation feature ID. */
     activeFeatureId: string | null;
+    /** Currently active annotation feature type. */
     activeFeatureType: AnnotationFeatureType | null;
 }
+/**
+ * Event emitted by the {@link AnnotationPlugin} when the annotation state changes.
+ */
 declare class AnnotationEvent extends MapEvent<AnnotationEventType> {
+    /** Current annotation mode (`creating`, `editing`, `idle`). */
     mode: AnnotationMode;
+    /** Whether the last operation can be undo. Use this flag to enable/disable undo UI. */
     canUndo: boolean;
+    /** Whether an operation can be redone. Use this flag to enable/disable redo UI. */
     canRedo: boolean;
+    /** Currently active annotation feature ID. */
     activeFeatureId: string | null;
+    /** Currently active annotation feature type. */
     activeFeatureType: AnnotationFeatureType | null;
+    /** Current set of annotation features. */
     features: AnnotationFeature[];
+    /**
+     * Constructs a new AnnotationEvent instance.
+     */
     constructor(type: AnnotationEventType, map: FlowCoreMap, data: AnnotationEventData);
 }
 
@@ -68,50 +103,332 @@ type SelectionEventType = 'selectionChanged';
 interface SelectionEventTypes {
     selectionChanged: (event: SelectionEvent) => void;
 }
+/**
+ * This event is emitted by the {@link SelectionPlugin} when selection state changes following user interaction.
+ *
+ * The event detail indicates which map data source has changed and its currently selected features.
+ * An empty `features` array indicates that no features are selected.
+ *
+ * @group Events
+ */
 declare class SelectionEvent extends MapEvent<SelectionEventType> implements MapSourceIdentifier {
+    /** Map data source ID */
     source: string;
+    /** Map data source layer ID */
     sourceLayer?: string;
+    /** Array of selected feature IDs */
     features: MapFeatureId[];
     constructor(type: SelectionEventType, map: FlowCoreMap, sourceIdentifier: MapSourceIdentifier, features: MapFeatureId[]);
 }
 
 type SelectionMode = 'single' | 'multi' | 'none';
+/**
+ * Selection options for a map data source passed to {@link SelectionPlugin.enableSelection}. See {@link SelectionPlugin} for more details.
+ */
 interface SelectionOptions {
+    /** Clear mode for selection */
     clear?: boolean | 'group';
+    /** Selection group ID - applies when `clear` mode is set to `group`. */
     group?: string;
+    /** Selection mode: `single` or `multi` */
     mode: SelectionMode;
+    /** ID of popup to display when selecting a feature. */
     popup?: string;
+    /** Reactive state property to bind to selection state. */
     selectionState?: string;
+    /** Map data source layer. Note that this is only required for custom vector data sources. */
     sourceLayer?: string;
 }
+/**
+ * @noInheritDoc
+ *
+ * This plugin provides selection functionality allowing a user to select features by clicking the map. It supports single or multiple feature selection, and can
+ * automatically display popups for selected features.
+ *
+ * Selection state is a property of a map data source (not a map layer) and is tracked independently for each map data source. To enable selection and configure options for a particular map data source call the {@link enableSelection} method of the plugin.
+ *
+ * **NOTE** To support selection the `featureId` property or the map data source must be defined to allow features to be uniquely identified.
+ *
+ * ## Selection Modes
+ *
+ * Selection modes can be configured individually for each of a map's data sources. The following modes are supported:
+ *
+ * | Mode | Behavior |
+ * |------|-------------|
+ * | `none` | Feature selection is disabled for the map data source. (default)|
+ * |`single`| Only one feature of the data source can be selected at a time. Selecting a new feature by clicking will deselect the previously selected feature. |
+ * |`multi` | Multiple features of the data source can be selected. A simple click on a feature will clear the selection state and select the clicked feature. A Ctrl/Alt/Meta click will toggle the selection state of the clicked feature, adding to or removing the feature from the selection.|
+ *
+ * ## Clearing selection
+ *
+ * Although selection state is handled independently for each map data source, it is possible to configure a map data source to clear its selection following user interaction with map features from another map data source.
+ * By default, clicking an empty area of the map will deselect all features from all map data sources. Set the {@link SelectionOptions.clear} option to configure how selection state behaves when interacting with other map data sources:
+ *
+ * | Clear mode | Behavior   |
+ * |------------|-------------|
+ * | `false`| Selection state is preserved when selecting features of another map data source. (default) |
+ * | `true` | Selection state is cleared when clicking a feature of another map data source. This option is useful for configuring mutually exclusive selection between map data sources.|
+ * | `group`| Selection state is cleared when clicking a feature of another map data source with the same `group` property. This option is useful for configuring mutually exclusive selection between a subset of data sources on a map.|
+ *
+ * ## Binding Feature Selection to Reactive State
+ *
+ * Setting the {@link SelectionOptions.selectionState} property when configuring selection for a map data source binds the selection state to a reactive state property.
+ * The binding is two-way: selecting features on the map will update the bound reactive property and updating the reactive property will update the selection state on the map.
+ *
+ * Referencing the bound reactive property in a reactive query or computed property will trigger a reactive update when the user selects or deselects features on the map.
+ *
+ * | Selection mode | Reactive binding |
+ * |------------|-------------|
+ * | `single`   | Single map feature ID (string or number) |
+ * | `multi`    | Array of map feature IDs |
+ *
+ * ## Selection events
+ *
+ * In addition to supporting binding to reactive state, the plugin also emits a `selectionChanged` event when selection state changes for a map data source.
+ *
+ * ## Popups
+ *
+ * Specify the ID of a popup to associate with a map data source using the {@link SelectionOptions.popup} property. The popup will be displayed automatically when a feature is selected by the user
+ * and closed when the feature is deselected. Currently, setting the selection state programmatically will not trigger the popup to be displayed.
+ *
+ * See (@link PopupPlugin} for more details of how to define and register popups.
+ *
+ *
+ * ## Styling selection state
+ *
+ * A selected feature has the `selected` feature state property set to `true`. This can be referenced in map layer style expressions to apply selection effects.
+ *
+ * @example
+ * Apply a selection effect using the `circleStrokeWidth` property:
+```js{14}
+import { SelectionPlugin } from '@emuanalytics/flow-rdf-core/plugins';
+const selectionPlugin = map.getPlugin(SelectionPlugin);
+
+selectionPlugin.enableSelection("airquality_source", {
+  mode: "multi"
+});
+
+const circleLayer = new MapLayer({
+  id: "circle-layer",
+  type: "circle",
+  source: "airquality_source",
+  style: layerStyle("circle")
+    .circleColor(expr(`@no2 ? from-palette('YlOrRd', @no2, 0, 100) : gray`))
+    .circleStrokeWidth(expr("@@selected ? 5 : 0"))
+    .circleRadius(expr(`@no2 ? @no2 / 5 : 5`))
+    .build()
+});
+```
+ * @example
+ * Add an event listener for `selectionChanged` events:
+```js
+ selectionPlugin.on('selectionChanged', (e) => {
+   console.log(`Selection changed for source: ${e.source}`);
+   console.log(`Selected features: ${e.features.join(',')}`);
+ });
+ ```
+*/
 declare class SelectionPlugin extends MapPluginBase<undefined, SelectionEventTypes> {
     private _sourceSelections;
     private _enablePopups;
     readonly name = "SelectionPlugin";
+    /**
+     * Constructs a new SelectionPlugin 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: PluginManager);
+    /**
+     * Clears selection for the specified map data source.
+     *
+     * @param source Map data source ID
+     */
     clearSelection(source: string): void;
+    /**
+     * Deselect the specified feature or features.
+     *
+     * @param source Map data source ID
+     * @param features feature ID or array of feature IDs to deselect
+     */
     deselectFeatures(source: string, features: MapFeatureId | MapFeatureId[]): void;
+    /**
+     * @internal
+     */
     destroy(): void;
+    /**
+     * Disable selection for the specified map data source.
+     *
+     * @param source Map data source ID
+     */
     disableSelection(source: string): void;
+    /**
+     * Enable selection support for the specified map data source.
+     *
+     * @param source Map data source ID
+     * @param options Selection options
+     */
     enableSelection(source: string, options: SelectionOptions): void;
+    /**
+     * @internal
+     */
     handleBeforeSourceRemoved(event: MapSourceEvent): void;
+    /**
+     * @internal
+     */
     handleClick(event: MapMouseEvent): void;
-    selectFeatures(source: string, features: MapFeatureId | MapFeatureId[]): void;
+    /**
+     * Select the specified feature or features.
+     *
+     * Use this method to programmatically select features on a map data source. This will update the selection state and trigger display of
+     * any associated popups if configured.
+     *
+     * @param source Map data source ID
+     * @param features feature ID or array of feature IDs to select
+     * @param showPopups Show popups for the selected features. Defaults to `true`.
+     */
+    selectFeatures(source: string, features: MapFeatureId | MapFeatureId[], showPopups?: boolean): void;
+    /**
+     * Gets the selected feature IDs for the specified map data source.
+     *
+     * @param source map data source ID
+     * @returns Array of selected feature IDs
+     */
     selectedFeatureIds(source: string): MapFeatureId[];
+    /**
+     * Returns a {@link MapFeatureStream} of selected features for the specified map data source.
+     *
+     * Subscribe to the stream to receive updates when the selection state changes and receive full feature property data
+     * from the map.
+     *
+     * @param source Map data source ID
+     * @returns {@link MapFeatureStream} of selected features
+     */
     selectedFeatureStream(source: string): MapFeatureStream;
-    enablePopups(enabled?: boolean): void;
+    /**
+     * Enable display of popups when a feature is clicked and an associated popup has been registered with the map data source.
+     * See {@link PopupPlugin} for more details of how to define and register popups.
+     *
+     * Note that popups are enabled by default.
+     */
+    enablePopups(): void;
+    /**
+     * Disable display of popups when a feature is clicked. This will also close any currently open popups.
+     */
     disablePopups(): void;
 }
 
+/**
+ * An {@link AnnotationPlugin} operation to support undo/redo functionality. Annotation operations are
+ * stored on the AnnotationPlugin's undo/redo stacks. State to undo and redo operations is captured as closures
+ * over the `do` and `undo` functions.
+ */
 interface AnnotationOperation {
+    /** Function to perform the operation. */
     do: Func;
+    /** Function to undo the operation. */
     undo: Func;
 }
+/**
+ * AnnotationPlugin configuration options specified when adding the plugin to a {@link FlowCoreMap} instance.
+ */
 interface AnnotationPluginOptions {
+    /**
+     * Set to `true` to enable user interaction to create and edit annotation features. Set to `false` to display
+     * fixed programmatically-created annotations.
+     */
     interactive?: boolean;
+    /** Default style to apply to annotation features. */
     defaultStyle?: Partial<AnnotationStyle>;
+    /** Selection options passed to {@link SelectionPlugin.enableSelection} when adding annotation layers to the map. */
     selectionOptions?: SelectionOptions;
 }
+/**
+ * @noInheritDoc
+ *
+ * This plugin provides functionality to allow a user to draw annotations on the map. It supports creating and editing:
+ *
+ * - Polygons
+ * - Circles with geographic center and radius
+ * - Line strings
+ * - Points with geographic center and pixel radius
+ *
+ * ### Data Model
+ *
+ * The {@link AnnotationPlugin} maintains a set of annotation features stored as GeoJSON features. In addition to the feature geometry,
+ * each feature has properties that define:
+ *
+ * - The feature's style (fill color, stroke color, label color, label text etc.)
+ * - The feature's visibility and selection state
+ *
+ * Methods are provided by the plugin to add features, remove features, and update feature properties. To respond to changes initiated by the user,
+ * the `annotationStateChanged` event is emitted by the plugin. See {@link AnnotationEvent} for full details.
+ *
+ * ## User interaction
+ *
+ * Th plugin handles all mouse events to allow a user to create and edit annotation features.
+ *
+ * Call {@link AnnotationPlugin.createdFeature} to start drawing a new feature. This is typically done when a user selects an annotation type to add from a palette or menu.
+ *
+ * Double-clicking by the user on an existing annotation feature on the map will initiate editing. To initiate editing programmatically, call {@link AnnotationPlugin.editFeature}.
+ *
+ * To programmatically delete an annotation feature, call {@link AnnotationPlugin.deleteFeature}.
+ *
+ * :::info
+ * The plugin registers keyboard shortcuts to commit editing, delete a feature, undo/redo an operation, and create a new feature.
+ * See {@link AnnotationPlugin.initialize} for details.
+ * :::
+ *
+ * ## Undo/Redo
+ *
+ * The plugin maintains undo/redo stacks of user-initiated operations to support unlimited undo and redo. Changes to the availability of undo/redo are
+ * communicated via the `annotationStateChanged` event to allow UI elements such as toolbar buttons to be enabled or disabled.
+ *
+ * ## Selection Support
+ *
+ * The plugin integrates with the {@link SelectionPlugin} to allow annotation features to be selected programmatically and to respond to selection of
+ * annotation features by the user.
+ *
+ * When registering the plugin, specify the {@link AnnotationPluginOptions.selectionOptions} parameter to enable selection
+ * of features from the annotation plugin's internal MapDataSource. Use the `mode`, `clear` and `group` selection options to determine how selection of annotation features
+ * interacts with selection of other map features. Specify the `selectionState` option to configure two-way binding of annotation selection with reactive state (see{@link SelectionPlugin}).
+ *
+ * Note that in creation or editing mode, the {@link AnnotationPlugin} disables hover styling
+ * and selection of other non-annotation map features.
+ *
+ * :::warning
+ * The SelectionPlugin must be registered by calling {@link FlowCoreMap.usePlugin} before the AnnotationPlugin is registered.
+ * :::
+ *
+ * ## How it works
+ *
+ * The plugin adds an internally-managed {@link MapDataSource} to expose its set of GeoJSON annotation features to the map. {@link MapLayer}s are also added to the map
+ * to display annotation feature fills, strokes and labels. Features are styled using MapLayer style rules referencing feature properties such as `strokeColor` and `labelText`.
+ *
+ * The plugin integrates [mapbox-gl-draw](https://github.com/mapbox/mapbox-gl-draw) to
+ * provide user interaction for creating and editing features.
+ *
+ * :::warning
+ * The plugin is not responsible for persistence of annotation features. It is up to the application to persist and reload features as required by handling
+ * the `annotationStateChanged` event to respond to changes and to call {@link AnnotationPlugin.setFeatures} to reload features.
+ * :::
+ *
+ * @example
+ * Initialize the plugin:
+```js
+// Selection plugin is required for annotation plugin to operate
+map.usePlugin(SelectionPlugin);
+
+// Initialize the annotation plugin
+const annotationPlugin = map.usePlugin(AnnotationPlugin, { selectionOptions: { mode: 'single' } });
+
+// Add handler for annotation state changes
+annotationPlugin.on('annotationStateChanged', (event) => {
+  console.log('Annotation state changed', event);
+});
+```
+ *
+ */
 declare class AnnotationPlugin extends MapPluginBase<AnnotationPluginOptions, AnnotationEventTypes> {
     readonly name = "AnnotationPlugin";
     private static _defaultOptions;
@@ -126,29 +443,161 @@ declare class AnnotationPlugin extends MapPluginBase<AnnotationPluginOptions, An
     private _annotationDataSource;
     private _drawControl;
     private _removeKeyboardShortcuts;
+    /**
+     * 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: PluginManager, options?: AnnotationPluginOptions);
+    /**
+     * @internal
+     *
+     * Called by {@link PluginManager} when the plugin is added to the map.
+     */
     initialize(): void;
+    /**
+     * @internal
+     *
+     * Called by {@link PluginManager} when the plugin is destroyed.
+     */
     destroy(): void;
+    /**
+     * Clears all map annotations and reset the plugin state.
+     *
+     * @returns The annotation plugin instance to allow method chaining
+     */
     clear(): 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(): this;
     /**
-     * Redo the last undone operation.
+     * Redoes the last operation on the redo stack.
+     *
+     * @returns The annotation plugin instance to allow method chaining
      */
     redo(): this;
+    /**
+     * Returns the specified annotation feature by id.
+     *
+     * @param featureId
+     */
     getFeature(featureId: string): AnnotationFeature;
+    /**
+     * Returns all annotation features.
+     */
     getFeatures(): AnnotationFeature[];
+    /**
+     * 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: Array<PartialBy<AnnotationFeature, 'id'>>): 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: PartialBy<AnnotationFeature, 'id'>): AnnotationFeature;
+    /**
+     * 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: string): 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: AnnotationFeatureType): void;
+    /**
+     * 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: string): void;
+    /**
+     * Zoom the map to the specified annotation feature.
+     *
+     * @param featureId
+     * @param animationOptions
+     * @returns The annotation plugin instance to allow method chaining
+     */
     zoomToFeature(featureId: string, animationOptions: MapAnimationOptions): 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: string, property: string, value: any): 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: string, properties: Record<string, any>): this;
+    /**
+     * Commits the current creation or editing operation.
+     *
+     * This operation can be undone.
+     *
+     * @returns The annotation plugin instance to allow method chaining
+     */
     commit(): this;
+    /**
+     * Cancel the current creation or editing operation.
+     *
+     * This operation **cannot** be undone.
+     *
+     * @returns The annotation plugin instance to allow method chaining
+     */
     cancel(): 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(): this;
+    /**
+     * @internal
+     *
+     * MapPluginBase event handler
+     */
     handleDblClick?(event: MapMouseEvent): void;
+    /**
+     * @internal
+     *
+     * MapPluginBase event handler
+     */
     handleBeforeStyleChanged(event: MapStyleChangeEvent): MapStyleSpecification;
     private startDrawing;
     private endDrawing;
@@ -166,90 +615,286 @@ declare class AnnotationPlugin extends MapPluginBase<AnnotationPluginOptions, An
 }
 
 interface DataJoinOptions {
-    /** Set to `true` to clear feature state before applying data join. */
+    /** Set to `true` to clear feature state before applying the data join. */
     clear?: boolean;
+    /** Data to join with map data source features. A datasetId, URL, reactive expression or an array of data objects. */
     data: string | any[];
-    /** Data join foreign key. */
+    /** Data join foreign key. The name of a property in the joined data to use as the unique identifier for the join.*/
     foreignKey: string;
+    /** Additional parameters to include when querying data to join. */
     parameters?: DataJoinParameter[];
+    /** Map data source ID to which the data join is applied. */
     source: string;
+    /** Map data source layer. This is only required for custom vector data sources. */
     sourceLayer?: string;
 }
+/**
+ * A data join parameter that is added to a dataset query when querying data to join.
+ */
 interface DataJoinParameter {
+    /** Parameter name */
     name: string;
+    /** Set to `true` if parameter must be non-null */
     required?: boolean;
+    /** Parameter value: reactive expression, literal number or boolean */
     value: string | number | boolean;
 }
+/**
+ * @internal
+ *
+ * Implementation of of a single data join.
+ */
 declare class DataJoin {
     readonly id: string;
     readonly map: FlowCoreMap;
     private static defaultOptions;
+    private options;
     private autorunDisposer;
+    /** Reactive expression that returns array of data objects to be joined. */
     private dataExpression;
-    private options;
+    /** Parameter key/value pairs where value is a reactive expression */
     private parameterExpressions;
     constructor(id: string, map: FlowCoreMap, options: DataJoinOptions);
     get source(): string;
+    /**
+     * 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(): void;
+    /**
+     * Stops the reactive data join.
+     */
     stop(): void;
+    /** Performs the data join given an array of data objects. */
     private doDataJoin;
+    /**
+     * Load data to join using the specified datasetId or a custom URL.
+     *
+     * Reactive parameters are added to the query as name/value querystring parameters.
+     */
     private loadData;
 }
 /**
- *  dfsffd
+ * @noInheritDoc
+ *
+ * This plugin provides data join functionality that allows additional non-geospatial data to be set as feature state on map features. This data can be accessed
+ * in {@link MapLayer} style expressions to style features based on the joined data.
+ *
+ * Typically, data joins are used to join dynamic data to static map features. This allows feature geometry to be queried once and then properties
+ * dynamically updated in-place. For example, consider a map displaying county polygons. The polygons can be loaded once and then styled to display different metrics
+ * using color or other style properties by applying a data join.
+ *
+ *
+ * ## Data sources
+ *
+ * The data to join is specified using the `data` property of the data join options when adding a data join.
+ * The supported sources of data match those supported by {@link MapDataSource}:
+ *
+ * | Data source  | Description   |
+ * |--------------|---------------|
+ * | Dataset ID   | Specify a dataset ID to load data from a Flo.w dataset. Any parameters configured for the data join will be included with the dataset query. |
+ * | URL          | Specify a URL to load data from a custom API. Any parameters configured for the data join will be included with the `GET` request as query string name/value pairs. |
+ * | Reactive expression | Specify a reactive expression that returns an array of data objects. This is typically a reactive query or a computed derivation of a reactive query. |
+ * | Array of data objects | Specify a literal array of data objects to join.  |
+ *
+ *
+ * ## Performing the join
+ *
+ * When loaded, non-geospatial data is joined with the {@link MapDataSource}'s features by matching the primary key of map features with a foreign key in the joined data. It is analogous to performing a LEFT JOIN in SQL.
+ * Use the `foreignKey` property of the data join options to specify the foreign key in the joined dataset. The primary key of the {@link MapDataSource}'s features is specified using the `featureId` property of the {@link MapDataSource}.
+ *
+ * Specify the `clear` property to determine the meaning of 'missing' features in the data to join. If set to `true`, joined data is cleared from all features before applying new joined data. This option is typically used when the joined data
+ * represents the complete current state and missing features are interpreted as 'no data'. If set to `false`, existing joined data is not cleared before applying new joined data. This option is typically used when the joined data represents a
+ * set of changes to apply to existing data as an update.
+ *
+ * The data join is performed reactively. This means that any changes to the data to join or the parameters used to query the data will automatically trigger a new data join.
+ *
+ * ## Accessing joined data
+ *
+ * Joined data is set using {@link FlowCoreMap.setFeatureState} on the {@link MapDataSource}'s features. It can be accessed using the `@@` notation in {@link MapLayer} style expressions
+ * to retrieve feature state. To access a property in a style expression use the following format: `@@<dataJoinID>.<propertyName>`.
+ * Joined data for a particular feature may be null if no data for that feature is present in the joined dataset. Use the ternary operator to supply a 'no data' value in style expressions.
+ *
+ * ## Restrictions
+ *
+ * The joined data is applied to a map data source using feature state properties. These properties can only be used to set 'paint-type' style properties including
+ * color, width, opacity, radius, etc. They cannot be used to set 'layout-type' style properties such as text labels that trigger layout processing.
+ *
+ * Joined data cannot be used in {@link MapLayer} filter expressions for the same reason. Filtering features requires map layout processing to be performed.
+ *
+ * See [Mapbox GL JS documentation](https://docs.mapbox.com/mapbox-gl-js/style-spec/expressions/#feature-state) for more information.
+ *
+ * @example
+ * Add a data join to a {@link MapDataSource}:
+```js
+import { DataJoinPlugin } from '@emuanalytics/flow-rdf-core/plugins';
+
+const dataJoinPlugin = map.getPlugin(DataJoinPlugin);
+
+dataJoinPlugin.addDataJoin('dataJoin1', {
+  data: '$queries.dataQuery.results',
+  source: 'cities-source',
+  foreignKey: 'cityId',
+  clear: true
+});
+```
+ *
+ * @example
+ * Access joined data in a {@link MapLayer} style expression:
+```js{8}
+const circleLayer = new MapLayer({
+  id: "circle-layer",
+  type: "circle",
+  source: "cities-source",
+  style: layerStyle("circle")
+    .circleColor(expr(`@no2 ? from-palette('YlOrRd', @no2, 0, 100) : gray`))
+    .circleStrokeWidth(expr("@@selected ? 5 : 0"))
+    .circleRadius(expr(`@@dataJoin1.totalPopulation ? @@dataJoin1.totalPopulation / 1000 : 5`))
+    .build()
+});
+```
+ *
  *
- *  @noInheritDoc
  *
  */
 declare class DataJoinPlugin extends MapPluginBase {
     private _joins;
     readonly name = "DataJoinPlugin";
+    /**
+     * 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: PluginManager);
+    /**
+     * 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: string, options: DataJoinOptions): void;
+    /**
+     * @internal
+     *
+     * Used internally to set the {@link StateStore} to use for retrieving reactive properties.
+     */
     bindState(state: StateStore): void;
+    /** @internal */
     destroy(): void;
+    /** @internal */
     handleSourceRemoved(event: MapSourceEvent): void;
+    /**
+     * Removes the specified data join from the map.
+     *
+     * @param id Data join ID
+     */
     removeDataJoin(id: string): void;
 }
 
 /** Callback function to indicate map export overlay drawing has finished. */
 type DrawOverlayCallback = (error: Error) => void;
-/** Function to draw an overlay on an exported map. */
+/**
+ * Function to draw an overlay on an exported map.
+ *
+ * If provided to {@link ExportPlugin.exportMap}, this function will be called after the map image has been rendered to the canvas.
+ * The function should draw the desired overlay on the canvas using the provided `ctx` (CanvasRenderingContext2D) and call
+ * the `callback` function when finished. Call the `callback` function with an error to indicate that drawing has failed.
+ *
+ * @param ctx The canvas context to draw on
+ * @param width The width of the canvas in pixels
+ * @param height The height of the canvas in pixels
+ * @param dpmm The resolution of the canvas in dots per mm
+ * @param callback Callback to be called when drawing is finished
+ *
+ */
 type DrawOverlayFn = (ctx: CanvasRenderingContext2D, width: number, height: number, dpmm: number, callback: DrawOverlayCallback) => void;
 /**
- * Options for [[FlowCoreMap.export]].
+ * Options for {@link ExportPlugin.exportMap}.
  */
 interface FlowMapExportOptions {
-    /** Name of exported file. */
+    /** Name of the exported file. */
     name: string;
-    /** Width of exported map in millimeters. */
+    /** Width of the exported map in millimeters. */
     width: number;
-    /** Height of exported map in millimeters. */
+    /** Height of the exported map in millimeters. */
     height: number;
-    /** Resolution of exported map. Dots/mm. */
+    /** Resolution of the exported map (dots per mm). */
     dpmm: number;
-    /** Format of exported map. */
+    /** Format of the exported map. Note that only `png` is currently supported. */
     format: 'png' | 'pdf';
     /**
-     * Geographic bounds of area to export ([left, bottom, right top]).
+     * Geographic bounds of the area to export ([left, bottom, right top]).
      *
      * This should be a subregion of the full map area.
+     *
+     * Note that `bounds` is ignored when exporting a map in globe projection at zoom levels below 4.
      */
     bounds?: number[];
-    /** Function called to draw overlay on exported map. */
+    /** Background color as CSS color value - this only applies when exporting a map in globe projection. (default = 'white') */
+    background?: string;
+    /** Optionally provide a function to draw an overlay over the map image before exporting to file. */
     drawOverlayFn?: DrawOverlayFn;
 }
 
+/**
+ * Note: ExportPlugin does not expose any options.
+ */
 interface ExportPluginOptions {
 }
+/**
+ * @noInheritDoc
+ *
+ * This plugin provides map export functionality. It currently allows exporting the map in PNG format only.
+ *
+ * @example
+ * Export the map to a PNG file:
+ * ```js
+// Get export plugin
+const exportPlugin = map.getPlugin(ExportPlugin);
+if (!exportPlugin) {
+  throw new Error('Export plugin not registered');
+}
+
+// Get visible bounds of map
+const bounds = map.getVisibleBounds();
+
+// Fixed export at A4 landscape (297x210mm) at 6dpmm
+await exportPlugin.exportMap({
+  name: `map-${DateTime.now().toFormat('yyyyMMddHHmmss')}`,
+  format: 'png',
+  width: 297,
+  height: 210,
+  dpmm: 6,
+  bounds
+});
+ ```
+ *
+ */
 declare class ExportPlugin extends MapPluginBase<ExportPluginOptions> {
     readonly name = "ExportPlugin";
+    /**
+     * Constructs an instance of the ExportPlugin. Note that this is called automatically
+     * when the plugin is registered with a map.
+     *
+     * @param pluginManager
+     */
     constructor(pluginManager: PluginManager);
+    /**
+     * 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: FlowMapExportOptions): Promise<string>;
 }
 
 /**
- * This plugin supports adding hover styling to map features.
+ * This plugin adds hover styling support to map features.
  *
  * When active, features that are hovered over will have their `hover`
  * feature state property set to `true`. This can be referenced in map layer
@@ -278,33 +923,97 @@ declare class ExportPlugin extends MapPluginBase<ExportPluginOptions> {
 declare class HoverEffectPlugin extends MapPluginBase {
     private hoveredFeature;
     readonly name = "HoverEffectPlugin";
+    /**
+     * Constructs a new HoverEffectPlugin 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: PluginManager);
+    /** @internal MapPluginBase handler */
     handleMouseMove(event: MapMouseEvent): void;
+    /** @internal MapPluginBase handler */
     handleMouseOut(event: MapEvent): void;
+    /** @internal MapPluginBase handler */
     handleSetExclusivePlugin(exclusivePlugins: MapPluginBase[]): void;
     private compareFeatures;
     private clearHover;
 }
 
+/**
+ * @noInheritDoc
+ *
+ * This plugin provides support for displaying popups on the map. It integrates with the SelectionPlugin to automatically display popups when
+ * map features are selected by the user. It also provides methods to open and close popups programmatically.
+ *
+ *
+ * @example
+ * Register a popup using a [lit-html](https://lit.dev/docs/v1/lit-html/introduction/) template and attach to feature selection:
+```js
+import { html } from '@emuanalytics/flow-rdf-core';
+import { PopupPlugin, SelectionPlugin } from '@emuanalytics/flow-rdf-core/plugins';
+
+const popupPlugin = map.getPlugin(PopupPlugin);
+const selectionPlugin = map.getPlugin(SelectionPlugin);
+
+popupPlugin.registerPopup('airqualityPopup', {
+  content: (feature) => html`
+    <h2>Air Quality</h2>
+    <ul>
+      <li>Name: ${feature?.properties.name}</li>
+      <li>NO2: ${feature?.properties.no2} ppm</li>
+    </ul>
+  `
+});
+
+selectionPlugin.enableSelection('airquality_source', {
+  mode: 'single',
+  selectionState: 'selectedFeatureId',
+  popup: 'airqualityPopup'
+});
+
+```
+ * See {@link MapPopup} for more information about defining and rendering popups.
+ */
 declare class PopupPlugin extends MapPluginBase {
     private _popupTemplates;
     private _popups;
     readonly name = "PopupPlugin";
+    /**
+     * Constructs a new PopupPlugin 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: PluginManager);
     registerPopup(id: string, options: MapPopupOptions): void;
+    /**
+     * Opens a popup following a mouse click event.
+     *
+     * @param id The ID of the registered popup to display
+     * @param event The mouse event associated with the popup
+     * @return The opened {@link MapPopup} instance
+     */
     openPopup(id: string, event: MapMouseEvent): MapPopup;
+    /**
+     * Opens a popup at the specified location. If `feature` is provided, the popup
+     * will have access to the corresponding map feature's properties for rendering
+     * the popup content.
+     *
+     * @param id The ID of the registered popup to display
+     * @param lngLat The coordinate at which to display the popup
+     * @param feature Feature to associate with the popup
+     * @return The opened {@link MapPopup} instance
+     */
     openPopup(id: string, lngLat: [number, number], feature?: MapFeatureIdentifier): MapPopup;
+    /**
+     * Closes all open popups.
+     */
     closeAllPopups(): void;
+    /**
+     * Closes open popups for the specified {@link MapDataSource}s.
+     */
     closePopupsForSources(sources: string | string[]): void;
 }
 
-declare class UrlSyncPlugin extends MapPluginBase {
-    readonly name = "UrlSyncPlugin";
-    constructor(pluginManager: PluginManager);
-    initialize(): void;
-    handleMoveEnd(event: MapEvent): void;
-    private mapStateToHash;
-    private hashToMapState;
-}
-
-export { AnnotationEvent, type AnnotationEventData, type AnnotationEventType, type AnnotationEventTypes, type AnnotationFeature, type AnnotationFeatureProps, type AnnotationFeatureType, type AnnotationMode, type AnnotationOperation, AnnotationPlugin, type AnnotationPluginOptions, type AnnotationStyle, type AnnotationsServiceConfig, DataJoin, type DataJoinOptions, DataJoinPlugin, type DrawOverlayCallback, type DrawOverlayFn, ExportPlugin, type ExportPluginOptions, type FlowMapExportOptions, HoverEffectPlugin, MapPluginBase, PluginManager, PopupPlugin, SelectionEvent, type SelectionEventType, type SelectionEventTypes, type SelectionMode, type SelectionOptions, SelectionPlugin, UrlSyncPlugin };
+export { AnnotationEvent, type AnnotationEventData, type AnnotationEventType, type AnnotationEventTypes, type AnnotationFeature, type AnnotationFeatureProps, type AnnotationFeatureType, type AnnotationMode, type AnnotationOperation, AnnotationPlugin, type AnnotationPluginOptions, type AnnotationStyle, DataJoin, type DataJoinOptions, DataJoinPlugin, type DrawOverlayCallback, type DrawOverlayFn, ExportPlugin, type ExportPluginOptions, type FlowMapExportOptions, HoverEffectPlugin, MapPluginBase, PluginManager, PopupPlugin, SelectionEvent, type SelectionEventType, type SelectionEventTypes, type SelectionMode, type SelectionOptions, SelectionPlugin };