@emuanalytics/flow-rdf-core 4.0.10 → 4.0.12

package/dist/shared/{flow-rdf-core.08156446.d.ts → flow-rdf-core.3da5bd49.d.ts}

@@ -1940,6 +1940,7 @@ declare class MapDataSource {
     private expandSrc;
 }
 
+/** Generates a new type by making a specified property of the original type `optional`. */
 type PartialBy<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
 
 declare class FlowMapError extends FlowCoreError {
@@ -1951,20 +1952,36 @@ interface MapSourceIdentifier {
     source: string;
     sourceLayer?: string;
 }
+/**
+ * A MapFeatureIdentifier uniquely identifies a map feature by its ID and source.
+ *
+ * Used to uniquely identify a map feature when displaying popups or when setting/getting map feature state (see {@link FlowCoreMap.setFeatureState} and {@link FlowCoreMap.getFeatureState}).
+ */
 interface MapFeatureIdentifier {
+    /** Unique feature ID */
     id: MapFeatureId;
+    /** ID of associated {@link MapDataSource} */
     source: string;
+    /** Map data source layer. Only required for custom vector data sources. */
     sourceLayer?: string;
 }
+/** A map feature associated with a {@link MapDataSource}. */
 interface MapFeature {
+    /** Feature geometry */
     geometry: GeoJSON.Geometry;
+    /** Unique feature ID */
     id?: MapFeatureId;
+    /** ID of associated {@link MapLayer}. */
     layer?: string;
+    /** Feature properties */
     properties: {
         [key: string]: any;
     };
+    /** ID of associated {@link MapDataSource} */
     source: string;
+    /** Map data source layer. Only required for custom vector data sources. */
     sourceLayer?: string;
+    /** Additional state associated with the feature. See {@link FlowCoreMap.setFeatureState}. */
     state?: {
         [key: string]: any;
     };
@@ -2019,7 +2036,7 @@ interface MapPaddingOptions {
 }
 
 /**
- * This interface defines all event types emitted {@link FlowCoreMap} and
+ * This interface defines all event types emitted by {@link FlowCoreMap} and
  * the type of the corresponding event handler.
  *
  * {@link FlowCoreMap} extends [EventEmitter](https://github.com/dashed/EventEmitter3) to provide
@@ -2117,15 +2134,41 @@ interface MapEventTypes {
      */
     error: (event: FlowMapError) => void;
 }
+/** The set of all map event types. */
 type MapEventType = keyof MapEventTypes;
+/**
+ * Base class providing a common interface for all map events.
+ *
+ * @group Events
+ *
+ * @typeParam EventType The type of the event.
+ * @typeParam TOrig The type of the original MapLibre event.
+ */
 declare class MapEvent<EventType extends string = MapEventType, TOrig = unknown> {
+    /** Event type */
     type: EventType;
+    /** Map instance that generated event */
     map: FlowCoreMap;
+    /** Original MapLibre event */
     originalEvent?: TOrig;
+    /** Creates an event from an original MapLibre event. */
     static fromMaplibreEvent(type: string, map: FlowCoreMap, maplibreEvent: MapLibreEvent): MapEvent<any, unknown>;
+    /**
+     * Constructs a map event.
+     *
+     * @param type Event type
+     * @param map Map instance that generated the event
+     * @param originalEvent Original MapLibre event that triggered the event
+     */
     constructor(type: EventType, map: FlowCoreMap, originalEvent?: TOrig);
 }
+/** Mouse event types. */
 type MapMouseEventType = 'click' | 'dblClick' | 'mouseMove' | 'mouseOut';
+/**
+ * Mouse event class providing a common interface for all mouse events.
+ *
+ * @group Events
+ */
 declare class MapMouseEvent extends MapEvent<MapMouseEventType, MouseEvent> {
     /**
      * The pixel coordinates of the mouse cursor, relative to the map and measured from the top left corner.
@@ -2135,23 +2178,48 @@ declare class MapMouseEvent extends MapEvent<MapMouseEventType, MouseEvent> {
      * The geographic location on the map of the mouse cursor.
      */
     lngLat: [number, number];
+    /**
+     * Features found at the mouse coordinate. Features are ordered by map layer with features higher in the layer stack appearing first in the `features` array.
+     * Features from non-interactive layers are excluded.
+     */
     features: MapFeature[];
     static fromMaplibreMouseEvent(type: MapMouseEventType, maplibreMouseEvent: MapMouseEvent$1, map: FlowCoreMap, features: MapFeature[]): MapMouseEvent;
     constructor(type: MapMouseEventType, map: FlowCoreMap, point: [number, number], lngLat: [number, number], features: MapFeature[], originalEvent: MouseEvent);
 }
+/** Source event types. */
 type SourceEventType = 'sourceAdded' | 'sourceRemoved' | 'beforeSourceAdded' | 'beforeSourceRemoved' | 'sourceFeatureState';
+/**
+ * Source event class providing a common interface for all source events.
+ *
+ * @group Events
+ */
 declare class MapSourceEvent extends MapEvent<SourceEventType> {
+    /** Map data source ID */
     source: string;
     constructor(type: SourceEventType, map: FlowCoreMap, source: string);
 }
+/** Loading event types. */
 type LoadingEventType = 'loading';
+/**
+ * Loading event class providing a common interface for all loading events.
+ *
+ * @group Events
+ */
 declare class MapLoadingEvent extends MapEvent<LoadingEventType> {
+    /** Indicates whether the map is currently loading data. */
     loading: boolean;
     constructor(map: FlowCoreMap, loading: boolean);
 }
+/**
+ * Style change event types.
+ *
+ * @group Events
+ */
 type StyleChangeEventType = 'beforeStyleChanged' | 'styleChanged';
 declare class MapStyleChangeEvent extends MapEvent<StyleChangeEventType> {
+    /** Old map style before changes. */
     oldStyle: MapStyleSpecification;
+    /** New map style after changes. */
     newStyle: MapStyleSpecification;
     constructor(type: StyleChangeEventType, map: FlowCoreMap, oldStyle: MapStyleSpecification, newStyle: MapStyleSpecification);
 }
@@ -2166,23 +2234,127 @@ interface RemoveListener {
     (): void;
 }
 
+/**
+ * The plugin manager is responsible for managing the lifecycle of map plugins and forwarding map events to plugin handlers. Each FlowCoreMap
+ * instance has a plugin manager associated with it, which is created when the map is initialized. The map instance provides the {@link FlowCoreMap.usePlugin}
+ * and {@link FlowCoreMap.getPlugin} for interacting with the plugin manager.
+ *
+ * Typically, it is not necessary to interact with the plugin manager directly unless you are implementing a custom plugin.
+ */
 declare class PluginManager {
     private _map;
     private _keyboardShortcutManager;
     private _plugins;
     private _initialized;
     private _exclusivePlugins;
+    /** Returns the parent FlowCoreMap instance. */
     get map(): FlowCoreMap<StateStore>;
+    /**
+     * Constructs a plugin manager for the provided FlowCoreMap instance. Note that plugin manager construction is performed automatically when a
+     * map is created.
+     */
     constructor(map: FlowCoreMap);
+    /**
+     * Register a plugin for use with a map. This will create an instance of the plugin and call its `initialize` method.
+     *
+     * Note that this is typically called using the `usePlugin` method of a {@link FlowCoreMap} instance.
+     *
+     * @example
+     * Register the HoverEffectPlugin for use with a map:
+  ```js
+    import { HoverEffectPlugin } from '@emuanalytics/flow-rdf-core/plugins';
+    map.usePlugin(HoverEffectPlugin);
+  ```
+     *
+     * @param plugin The plugin constructor to register. This must be a class that extends {@link MapPluginBase}
+     * @param options Plugin-specific options (if any) to pass to the plugin constructor
+     * @typeParam T Type of the plugin being registered
+     * @returns The registered plugin instance
+     */
     usePlugin<T extends MapPluginBase>(plugin: PluginConstructor<T>, options?: PluginOptionsType<T>): T;
+    /**
+     * Retrieve a plugin previously registered with a map. This is necessary to access plugin-specific methods or properties.
+     *
+     * Note that this is typically called using the {@link FlowCoreMap.getPlugin} method.
+     *
+     * @example
+     * Retrieve the SelectionPlugin and clear all selections for a specified map data source:
+  ```js
+    const selectionPlugin = map.getPlugin(SelectionPlugin);
+    selectionPlugin.selectFeatures('data-source', []);
+  ```
+     *
+     * @param plugin The plugin to retrieve (identified by the plugin constructor or name)
+     * @typeParam T Type of the plugin being retrieved
+     * @returns The registered plugin instance
+     */
     getPlugin<T extends MapPluginBase = MapPluginBase>(pluginOrName: PluginConstructor<T> | string): T;
+    /**
+     * Unregister the specified plugin.
+     *
+     * @param pluginOrName The plugin to unregister (identified by the plugin constructor or name)
+     * @returns The plugin manager instance to allow method chaining
+     * @typeParam T Type of the plugin being unregistered
+     */
     removePlugin<T extends MapPluginBase>(pluginOrName: PluginConstructor<T> | string): this;
+    /**
+     * Unregister all plugins.
+     *
+     * @returns The plugin manager instance to allow method chaining
+     */
     removeAllPlugins(): this;
+    /**
+     * Mark the specified plugin as 'exclusive'. This disables other non-exclusive plugins until the {@link removeExclusivePlugin} method is called.
+     *
+     * This is used by the annotation plugin to disable map selection and hover effects when annotation features are being drawn by the user.
+     */
     setExclusivePlugin(plugin: MapPluginBase): this;
+    /**
+     * Remove the 'exclusive' flag from the specified plugin. This allows other non-exclusive plugins to receive events again.
+     */
     removeExclusivePlugin(plugin: MapPluginBase): this;
+    /**
+     * This method is called by plugins to register keyboard shortcuts with the {@link KeyboardShortcutManager}.
+     *
+     * @example
+     * Register keyboard shortcuts from a map plugin:
+   ```js
+    // Add shortcuts
+    this.removeShortcuts = this.pluginManager.addKeyboardShortcuts({
+       'Enter,Escape': () => this.commit(),
+       KeyP: () => this.createFeature('Polygon'),
+       KeyL: () => this.createFeature('LineString'),
+       KeyM: () => this.createFeature('Point'),
+       KeyC: () => this.createFeature('Circle')
+    });
+  
+  ...
+  
+  // Remove shortcuts
+  this.removeShortcuts();
+  ```
+     *
+     * @param keyboardShortcuts Key bindings to register
+     * @param priority Key binding priority
+     * @returns Function that can be called to remove the keyboard shortcuts
+     */
     addKeyboardShortcuts(keyboardShortcuts: Bindings, priority?: number): RemoveListener;
+    /**
+     * This method is called internally to forward map events to active plugin handlers.
+     *
+     * @param eventName The event to forward
+     * @param args Event arguments
+     */
     forwardEvent<T extends keyof MapEventTypes>(eventName: T, ...args: Parameters<MapEventTypes[T]>): void;
+    /**
+     * This method is called internally to forward map style change events to active plugin handlers.
+     *
+     * @param eventName The event to forward
+     */
     forwardStyleChangeEvent(event: MapStyleChangeEvent): MapStyleSpecification;
+    /**
+     * This method is called internally to forward exclusivity changes to registered plugins.
+     */
     private forwardSetExclusivePlugin;
 }
 
@@ -2193,30 +2365,65 @@ type EventHandlers<T> = {
     [P in keyof T as P extends string ? `handle${Capitalize<P>}` : never]+?: T[P];
 };
 interface MapPluginBase<Options = any, Events extends EventEmitter.ValidEventTypes = string | symbol> {
+    /** Implemented by a plugin to perform initialization tasks. This method is called by the {@link PluginManager} when a plugin is created. */
     initialize?(): void;
+    /** Implemented by a plugin to perform clean-up tasks. This method is called by the {@link PluginManager} when a plugin is destroyed. */
     destroy?(): void;
+    /** Implemented by a plugin to handle map click events. */
     handleClick?(event: MapMouseEvent): void;
+    /** Implemented by a plugin to handle map double-click events. */
     handleDblClick?(event: MapMouseEvent): void;
+    /** Implemented by a plugin to handle mouse move events. */
     handleMouseMove?(event: MapMouseEvent): void;
+    /** Implemented by a plugin to handle mouse out events. */
     handleMouseOut?(event: MapEvent): void;
+    /** Implemented by a plugin to handle map move end events. */
     handleMoveEnd?(event: MapEvent): void;
+    /** Implemented by a plugin to handle source added events. */
     handleSourceAdded?(event: MapSourceEvent): void;
+    /** Implemented by a plugin to handle source removed events. */
     handleSourceRemoved?(event: MapSourceEvent): void;
+    /** Implemented by a plugin to handle before-source-added events. */
     handleBeforeSourceAdded?(event: MapSourceEvent): void;
+    /** Implemented by a plugin to handle before-source-removed events. */
     handleBeforeSourceRemoved?(event: MapSourceEvent): void;
+    /** Implemented by a plugin to handle feature state events.*/
     handleSourceFeatureState?(event: MapSourceEvent): void;
+    /** Implemented by a plugin to handle before-style-changed events. */
     handleBeforeStyleChanged?(event: MapStyleChangeEvent): MapStyleSpecification | undefined;
+    /** Implemented by a plugin to handle style changed events. */
     handleStyleChanged?(event: MapStyleChangeEvent): void;
+    /** Implemented by a plugin to handle map loading events. */
     handleLoading?(event: MapLoadingEvent): void;
+    /** Implemented by a plugin to handle map loading events. */
     handleSetExclusivePlugin?(exclusivePlugins: MapPluginBase[]): void;
+    /** Implemented by a plugin to handle map error events. */
     handleError?(error: FlowMapError): void;
 }
+/**
+ * Base class for map plugins. This provides a common interface for all map plugins and defines the available handlers that
+ * a plugin can implement. The {@link PluginManager} is responsible for managing the lifecycle of plugins and calling the appropriate handlers when events occur.
+ *
+ * Flo.w RDF Core provides a number of built-in plugins that extend the functionality of the map, such as the {@link HoverEffectPlugin} and {@link PopupPlugin}.
+ * Custom plugins can be created by extending {@link MapPluginBase} and implementing the desired handlers.
+ *
+ * @typeParam Options Type for plugin options. This is used to define the plugin-specific options that can be passed to the plugin when it is created.
+ * @typeParam Events Type for plugin events. This is used to define the events that the plugin can emit.
+ *
+ * @noInheritDoc
+ */
 declare abstract class MapPluginBase<Options extends object | undefined = any, Events extends EventEmitter.ValidEventTypes = string | symbol> extends EventEmitter<Events> {
     private _pluginManager;
     options: Options;
+    /**
+     * The map instance associated with this plugin.
+     */
     get map(): FlowCoreMap<StateStore>;
+    /** The {@link PluginManager} that is managing this plugin. */
     get pluginManager(): PluginManager;
+    /** The name of this plugin. This is used as a unique identifier when registering and retrieving a plugin. */
     abstract readonly name: string;
+    /** Constructs an plugin instance. Note this this is called internally when registering a plugin. */
     constructor(pluginManager: PluginManager, options?: Options);
 }
 
@@ -2236,7 +2443,31 @@ interface ImageRegistryEntry {
  *
  * The `ImageRegistry` is a container for map icon images.
  *
- * Images can be registered and retrieved by ID.
+ * Registered images can be used in `symbol` map layers by using the registered `is` as the `iconImage` style property.
+ *
+ * :::warning
+ * To fully support recoloring and halo effects, the source image should be a SDF (signed distance field) image.
+ * :::
+ *
+ * @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')
+});
+ ```
+ *
+ *
+ *
  */
 declare class ImageRegistry {
     private _registry;
@@ -2302,6 +2533,16 @@ interface FeatureStreamOptions {
  * A observable stream of map feature data. Subscribe to an instance of this class to receive
  * updates when map feature data changes.
  *
+ * :::warning
+ * If the map is panned or zoomed by the user, features that are no longer visible may be unloaded
+ * from the map. If a feature that is being tracked is unloaded, it will be removed from
+ * feature stream updates.
+ *
+ * If it is essential to track a feature even when it is unloaded, consider using a Flo.w reactive
+ * query independently of map data.
+ *
+ * :::
+ *
  * See {@link FlowCoreMap.featureStream } for usage information.
  */
 declare class MapFeatureStream {
@@ -2363,7 +2604,12 @@ declare class MapFeatureStream {
 interface MapOptions<TState extends StateStore = StateStore> extends Omit<MapOptions$1, 'style'> {
     /** Unique map identifier. */
     id?: string;
-    /** Base map style */
+    /**
+     * Base map style.
+     *
+     * Specify a pre-defined base style identifier or supply a complete Maplibre style specification.
+     *
+     */
     baseStyle?: string | MapStyleSpecification;
     /** Map container selector or element. This specifies where in the DOM the map will be inserted.  */
     container: string | HTMLElement;
@@ -2380,8 +2626,58 @@ interface MapOptions<TState extends StateStore = StateStore> extends Omit<MapOpt
     contextId?: string;
 }
 /**
+ * The core map class providing a high-level declarative API for creating and updating interactive maps.
+ *
+ * {@link FlowCoreMap} wraps the [Maplibre GL JS](https://maplibre.org/maplibre-gl-js/docs/) API to add reactive updating
+ * and declarative map data sources and layers. FlowCoreMap integrates with Flo.w reactive queries and reactive state to
+ * ensure that the map is in sync with the underlying data.
  *
+ * :::info
+ * FlowCoreMap provides basic map functionality. Other features such as popups, selection, and exporting map images are
+ * provided by plugins. See {@link FlowCoreMap.usePlugin} for more information.
+ * :::
  *
+ * @example
+ * Creating a basic map:
+```ts
+   import { FlowCoreMap } from '@emuanalytics/flow-rdf-core';
+
+   // Create a new map instance
+   const map = new FlowCoreMap({
+     id: 'air-quality-map',
+     container: '#map-container',
+     baseStyle: 'fjord',
+   });
+
+   // Wait for the map to be initialized
+   map.initialized.then(() => {
+
+     // Create a map data source that loads geospatial data from the `airquality` Flo.w dataset.
+     const source = new MapDataSource({
+       id: 'airquality-source',
+       type: 'vector',
+       src: 'airquality',
+       featureId: 'label'
+     });
+
+     // Create a map layer that uses the data source and displays circles for each feature.
+     const circleLayer = new MapLayer({
+       id: 'circle-layer',
+       type: 'circle',
+       source: 'airquality-source',
+       style: layerStyle('circle')
+         .circleColor('red)
+         .circleRadius(10)
+         .build()
+     });
+
+     // Add the data source and layer to the map.
+     map.transaction(() => {
+       map.addSource(source);
+       map.addLayer(circleLayer);
+     });
+   });
+```
  */
 declare class FlowCoreMap<TState extends StateStore = StateStore> extends EventEmitter$1<MapEventTypes> {
     private static _defaultOptions;
@@ -2627,7 +2923,31 @@ declare class FlowCoreMap<TState extends StateStore = StateStore> extends EventE
      * 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.
+     * 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.
@@ -2796,32 +3116,110 @@ declare class FlowCoreMap<TState extends StateStore = StateStore> extends EventE
     private updateMapStyle;
 }
 
+/**
+ * A template function for rendering popup content. The function receives the associated
+ * map feature and the reactive state store as arguments. The function can reference
+ * feature properties and reactive state properties to render the popup content.
+ *
+ * The function should return popup content in one of the following formats:
+ * - An HTML string (set as the innerHTML of the popup)
+ * - An HTML node (appended to the popup)
+ * - A [lit-html](https://lit.dev/docs/v1/lit-html/introduction/) template
+ *
+ * The template function is called reactively whenever the feature or state changes to
+ * re-render the popup content. If a lit-html template is returned, the popup will be re-rendered
+ * efficiently using a minimal set of DOM updates.
+ *
+ * @param feature The map feature associated with the popup
+ * @param state The reactive state store to access reactive properties
+ *
+ */
 type MapPopupTemplateFn<TState extends StateStore = StateStore> = (feature: MapFeature | null, state: TState) => string | Node | lit.TemplateResult;
+/** Popup events emitted by {@link MapPopup} */
 interface MapPopupEvents {
     closed: (popup: MapPopup) => void;
 }
 /**
- * [[MapPopup]] options.
+ * Creation options for a {@link MapPopup}.
  */
 interface MapPopupOptions {
     /** Specify a CSS class to add to the popup. */
     class?: string;
-    /** Enable 'close' button. */
+    /** Enable the popup's 'close' button. */
     closeButton?: boolean;
-    /** Enable closing popup on click on map. */
+    /** Enable closing the popup when the user clicks the map. */
     closeOnClick?: boolean;
-    /** Enable closing pop when map is moved. */
+    /** Enable closing the popup when the map is moved. */
     closeOnMove?: boolean;
-    /** Specify popup content as HTML string or HTML node. */
+    /** Specify the popup content as an HTML string, HTML node or a template function. */
     content: string | Node | MapPopupTemplateFn;
     /** Maximum width of popup in CSS units. */
     maxWidth?: string;
+    /** Enable repositioning the popup when its associated map feature moves. (default true) */
     trackFeature?: boolean;
 }
 /**
- * Core functionality for Flo.w map popups.
+ * A {@link MapPopup} instance is used to display information about a map feature as a popup on a {@link FlowCoreMap}. The content of the popup
+ * can be defined as static HTML or a template function that has access to the map feature's properties and the reactive state store.
+ *
+ * ## Rendering popup content
+ *
+ * Popup content can be defined at time of creation in one of the following ways:
+ * - An HTML string
+ * - An HTML node
+ * - A template function that returns one of the above **or** a [lit-html](https://lit.dev/docs/v1/lit-html/introduction/) template
+ *
+ * If content is provided using a template function, the function is called reactively whenever the associated map feature or state changes.
+ * The popup will be re-rended using the updated content returned from the template function. If using a lit-html template, the popup will be re-rendered
+ * efficiently using a minimal set of DOM updates. If the template function returns a static HTML string or node, the popup content will be replaced with the
+ * new content.
+ *
+ * ## Automatic feature tracking
  *
+ * A popup is usually anchored to its associated map feature, which is specified when opening the popup. Following a map data source update, if the feature has
+ * moved then the popup will be repositioned to the new location. This is enabled by default using the `trackFeature` option. Set `trackFeature` to `false` to disable
+ * this behavior.
  *
+ * :::info
+ * It is usually more convenient to use the {@link PopupPlugin} to create and manage popups automatically when features are selected by the user.
+ * {@link MapPopup} can be used directly for custom use cases.
+ * :::
+ *
+ * @example
+ * Create a popup and open manually at a specific location:
+```js
+import { MapPopup } from '@emuanalytics/flow-rdf-core';
+
+const popup = new MapPopup(map, {
+  content: 'Hello World',
+  closeButton: true,
+  maxWidth: '200px'
+});
+
+popup.open([-1, 51.5]);
+...
+popup.close();
+```
+ *
+ *  Create a popup following a mouse click event to track a map feature:
+```js
+import { MapPopup, html } from '@emuanalytics/flow-rdf-core';
+
+map.on('click', (event) => {
+  if (event.features.length > 0) {
+    // Feature clicked
+    const feature = event.features[0];
+    const popup = new MapPopup(event.map, {
+      // Content specified as a lit-html template function
+      content: (feature) => html`Clicked on ${feature?.properties.name}`,
+      closeButton: true
+    });
+
+    // Open the popup at location of mouse click and attach it to the clicked feature
+    popup.open(event);
+  }
+});
+```
  */
 declare class MapPopup extends EventEmitter$1<MapPopupEvents> {
     readonly map: FlowCoreMap;
@@ -2832,35 +3230,68 @@ declare class MapPopup extends EventEmitter$1<MapPopupEvents> {
     private _maplibrePopup;
     private _featureStreamDisposer?;
     /**
-     * Constructs a new `MapPopup` instance.
+     * Constructs a new {@link MapPopup} instance.
      *
-     * This is called by the `FlowMap::openPopup` method.
+     * Typically, a popup is created by interacting with the PopupPlugin or SelectionPlugin rather than instantiating a popup directly.
      *
-     * @param map Parent Flo.w map.
-     * @param options Popup options.
+     * @param map Parent map
+     * @param options Popup options
      */
     constructor(map: FlowCoreMap, options: MapPopupOptions);
+    /**
+     * Get the map feature associated with the popup.
+     */
     get feature(): MapFeatureIdentifier | undefined;
     /**
      * Close the popup.
      */
     close(): void;
     /**
-     * Move the popup to a new location.
+     * Move the popup to the specified location.
      *
      * @param lngLat New location.
      */
     moveTo(lngLat: [number, number]): void;
     /**
-     * Open the popup at the specified location.
+     * Open the popup by providing a mouse event.
+     *
+     * The popup position and associated map feature are determined from the event.
      *
-     * @param lngLat Popup location.
+     * @param event Mouse event triggering the popup
      */
     open(event: MapMouseEvent): void;
+    /**
+     * Open the popup by providing a location and associated map feature to display in the popup.
+     *
+     * @param lngLat Coordinate at which to display the popup
+     * @param feature Map feature to associate with the popup
+     */
     open(lngLat: [number, number], feature?: MapFeatureIdentifier): void;
+    /**
+     * Returns CSS classes to add to the popup.
+     */
     private cssClasses;
+    /**
+     * Update the popup in response to feature data changes.
+     *
+     * The popup may be moved or re-rendered depending on the nature of the
+     * feature changes.
+     *
+     * @param feature Map feature associated with the popup
+     */
     private handleFeatureUpdate;
+    /**
+     * Called when the popup is closed to clean up resources.
+     */
     private popupCloseHandler;
+    /**
+     * Render the popup content.
+     *
+     * If the content is defined using a template function, the function is called passing
+     * in the associated map feature and the reactive state store.
+     *
+     * @param feature The map feature associated with the popup.
+     */
     private renderContent;
 }