@emuanalytics/flow-rdf-core 4.2.0 → 4.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,7 +1,7 @@
1
1
  import maplibre from '@emuanalytics/maplibre-gl';
2
2
  import Debug from 'debug';
3
3
  import EventEmitter from 'eventemitter3';
4
- import { runInAction } from 'mobx';
4
+ import { runInAction, reaction } from 'mobx';
5
5
  import { toStream } from 'mobx-utils';
6
6
  import { FlowMapError } from '../errors/flow-map-error.mjs';
7
7
  import { assert } from '../utils/assert.mjs';
@@ -65,6 +65,10 @@ const _FlowCoreMap = class _FlowCoreMap extends EventEmitter {
65
65
  __publicField(this, "_style");
66
66
  __publicField(this, "_styleUpdateSubscription", null);
67
67
  __publicField(this, "_reportedStyleProblems", /* @__PURE__ */ new Set());
68
+ // Composite layer ID to the issues already emitted for it, and the composite layers checked for SelectionPlugin
69
+ __publicField(this, "_reportedCompositeIssues", /* @__PURE__ */ new Map());
70
+ __publicField(this, "_checkedCompositeSelection", /* @__PURE__ */ new Map());
71
+ __publicField(this, "_compositeLayerReaction");
68
72
  __publicField(this, "_throttledMouseMove", throttle(this.handleMouseMove, MOUSE_MOVE_THROTTLE_DURATION, { context: this }));
69
73
  __publicField(this, "_maplibreMap");
70
74
  __publicField(this, "updateMapStyle", (style) => {
@@ -84,7 +88,10 @@ const _FlowCoreMap = class _FlowCoreMap extends EventEmitter {
84
88
  ..._FlowCoreMap._defaultOptions,
85
89
  ...options
86
90
  };
87
- this._style = new MapStyle();
91
+ this._style = new MapStyle({
92
+ prepare: (source) => this.prepareSource(source),
93
+ event: (type, id) => this.emitEvent(new MapSourceEvent(type, this, id))
94
+ });
88
95
  this._debouncedEmitSourceEvent = debounceWithArgs(this.emitEvent, 20, {
89
96
  hash: (event) => event.source,
90
97
  context: this
@@ -93,6 +100,7 @@ const _FlowCoreMap = class _FlowCoreMap extends EventEmitter {
93
100
  this._resolveInitialized = resolve;
94
101
  });
95
102
  this._pluginManager = new PluginManager(this);
103
+ this._compositeLayerReaction = this.watchCompositeLayers();
96
104
  this.initialize();
97
105
  }
98
106
  /**
@@ -172,10 +180,7 @@ const _FlowCoreMap = class _FlowCoreMap extends EventEmitter {
172
180
  addSource(sourceOrOptions) {
173
181
  const source = isPlainObject(sourceOrOptions) ? new MapDataSource(sourceOrOptions) : sourceOrOptions;
174
182
  this.emitEvent(new MapSourceEvent("beforeSourceAdded", this, source.id));
175
- source.setFlowEndpoint({
176
- host: this.context.flowClient.baseUrl,
177
- apiKey: this.context.flowClient.apiKey || void 0
178
- });
183
+ this.prepareSource(source);
179
184
  this._style.addSource(source);
180
185
  this.emitEvent(new MapSourceEvent("sourceAdded", this, source.id));
181
186
  return source;
@@ -185,6 +190,7 @@ const _FlowCoreMap = class _FlowCoreMap extends EventEmitter {
185
190
  */
186
191
  destroy() {
187
192
  this._pluginManager.removeAllPlugins();
193
+ this._compositeLayerReaction();
188
194
  this._styleUpdateSubscription?.unsubscribe();
189
195
  this._maplibreMap?.remove();
190
196
  if (this.context) {
@@ -409,9 +415,14 @@ const _FlowCoreMap = class _FlowCoreMap extends EventEmitter {
409
415
  * @param id - Map data source ID
410
416
  */
411
417
  removeSource(id, removeLayers = false) {
412
- this.emitEvent(new MapSourceEvent("beforeSourceRemoved", this, id));
418
+ const owned = this._style.isOwnedSource(id);
419
+ if (!owned) {
420
+ this.emitEvent(new MapSourceEvent("beforeSourceRemoved", this, id));
421
+ }
413
422
  this._style.removeSource(id, removeLayers);
414
- this.emitEvent(new MapSourceEvent("sourceRemoved", this, id));
423
+ if (!owned) {
424
+ this.emitEvent(new MapSourceEvent("sourceRemoved", this, id));
425
+ }
415
426
  return this;
416
427
  }
417
428
  /**
@@ -648,6 +659,13 @@ const _FlowCoreMap = class _FlowCoreMap extends EventEmitter {
648
659
  usePlugins(plugins) {
649
660
  plugins.forEach((plugin) => this.usePlugin(plugin));
650
661
  }
662
+ /** Makes a source use the map's Flo.w endpoint to expand dataset and tile source IDs to URLs. */
663
+ prepareSource(source) {
664
+ source.setFlowEndpoint({
665
+ host: this.context.flowClient.baseUrl,
666
+ apiKey: this.context.flowClient.apiKey || void 0
667
+ });
668
+ }
651
669
  get formattedName() {
652
670
  return `FlowMap<${this._options.id}>`;
653
671
  }
@@ -705,6 +723,70 @@ const _FlowCoreMap = class _FlowCoreMap extends EventEmitter {
705
723
  return [this.featureFromMaplibreFeature(feature, layer)];
706
724
  });
707
725
  }
726
+ /**
727
+ * Follows the composite layers on the map: emits each new issue of each one as a map error, and checks that a
728
+ * composite layer that declares selection has the SelectionPlugin to enable it.
729
+ */
730
+ watchCompositeLayers() {
731
+ return reaction(
732
+ () => this._style.getLayers((layer) => layer.type === "composite").map((layer) => ({
733
+ id: layer.id,
734
+ issues: layer.issues,
735
+ selection: (layer.ownedSources ?? []).filter((source) => source.selection).map((source) => source.id)
736
+ })),
737
+ (composites) => {
738
+ this.reportCompositeIssues(composites);
739
+ this.checkCompositeSelection(composites);
740
+ },
741
+ { fireImmediately: true }
742
+ );
743
+ }
744
+ /** Emits each issue of a composite layer that wasn't among its issues when last reported. */
745
+ reportCompositeIssues(composites) {
746
+ const reported = /* @__PURE__ */ new Map();
747
+ composites.forEach(({ id, issues }) => {
748
+ const previous = this._reportedCompositeIssues.get(id);
749
+ const current = /* @__PURE__ */ new Set();
750
+ issues.forEach((issue) => {
751
+ const key = `${issue.severity} ${issue.path} ${issue.message}`;
752
+ if (!previous?.has(key) && !current.has(key)) {
753
+ this.emitError(`composite layer '${id}': ${issue.severity} at ${issue.path || "the spec"}: ${issue.message}`);
754
+ }
755
+ current.add(key);
756
+ });
757
+ reported.set(id, current);
758
+ });
759
+ this._reportedCompositeIssues = reported;
760
+ }
761
+ /**
762
+ * Emits one error for each composite layer that declares selection while the SelectionPlugin isn't installed. The
763
+ * check waits for the code that added the layer to finish, so that it can install the plugin after the layer.
764
+ */
765
+ checkCompositeSelection(composites) {
766
+ const declaring = composites.filter(({ selection }) => selection.length);
767
+ this._checkedCompositeSelection = new Map(
768
+ [...this._checkedCompositeSelection].filter(([id]) => declaring.some((composite) => composite.id === id))
769
+ );
770
+ declaring.filter(({ id }) => !this._checkedCompositeSelection.has(id)).forEach(({ id, selection }) => {
771
+ const check = {};
772
+ this._checkedCompositeSelection.set(id, check);
773
+ queueMicrotask(() => {
774
+ if (this._checkedCompositeSelection.get(id) === check && !this.hasPlugin("SelectionPlugin")) {
775
+ this.emitError(
776
+ `composite layer '${id}' declares selection on data source ${selection.map((s) => `'${s}'`).join(", ")}, but the SelectionPlugin isn't installed, so it renders without selection`
777
+ );
778
+ }
779
+ });
780
+ });
781
+ }
782
+ hasPlugin(name) {
783
+ try {
784
+ this._pluginManager.getPlugin(name);
785
+ return true;
786
+ } catch {
787
+ return false;
788
+ }
789
+ }
708
790
  /** Reports each new problem that {@link MapStyle} found while building the style as a map error. */
709
791
  reportStyleProblems() {
710
792
  const problems = this._style.styleProblems;
@@ -1,5 +1,5 @@
1
- import { af as MapEvent, ac as FlowCoreMap, a8 as MapSourceIdentifier, aH as MapFeatureId, aI as MapPluginBase, aJ as PluginManager, ah as MapSourceEvent, ag as MapMouseEvent, a9 as MapFeatureStream, aK as PartialBy, a3 as MapAnimationOptions, aj as MapStyleChangeEvent, M as MapStyleSpecification, S as StateStore, al as MapPopupOptions, am as MapPopup, a6 as MapFeatureIdentifier } from '../../../shared/flow-rdf-core.c45eb675.mjs';
2
- export { aO as EventHandlers, aN as PluginConstructor, aM as PluginEventsType, aL as PluginOptionsType } from '../../../shared/flow-rdf-core.c45eb675.mjs';
1
+ import { ao as MapEvent, al as FlowCoreMap, a9 as SelectionOptions, aQ as MapPluginBase, aR as PluginManager, aS as PartialBy, ac as MapAnimationOptions, ap as MapMouseEvent, as as MapStyleChangeEvent, f as MapStyleSpecification, S as StateStore, aq as MapSourceEvent, au as MapPopupOptions, av as MapPopup, af as MapFeatureIdentifier, ah as MapSourceIdentifier, aT as MapFeatureId, ai as MapFeatureStream } from '../../../shared/flow-rdf-core.62a36d8b.mjs';
2
+ export { aX as EventHandlers, aW as PluginConstructor, aV as PluginEventsType, aU as PluginOptionsType, a8 as SelectionMode } from '../../../shared/flow-rdf-core.62a36d8b.mjs';
3
3
  import { F as Func } from '../../../shared/flow-rdf-core.63162669.mjs';
4
4
  import 'eventemitter3';
5
5
  import 'lit-html';
@@ -99,226 +99,6 @@ declare class AnnotationEvent extends MapEvent<AnnotationEventType> {
99
99
  constructor(type: AnnotationEventType, map: FlowCoreMap, data: AnnotationEventData);
100
100
  }
101
101
 
102
- type SelectionEventType = 'selectionChanged';
103
- interface SelectionEventTypes {
104
- selectionChanged: (event: SelectionEvent) => void;
105
- }
106
- /**
107
- * This event is emitted by the {@link SelectionPlugin} when selection state changes following user interaction.
108
- *
109
- * The event detail indicates which map data source has changed and its currently selected features.
110
- * An empty `features` array indicates that no features are selected.
111
- *
112
- * @group Events
113
- */
114
- declare class SelectionEvent extends MapEvent<SelectionEventType> implements MapSourceIdentifier {
115
- /** Map data source ID */
116
- source: string;
117
- /** Map data source layer ID */
118
- sourceLayer?: string;
119
- /** Array of selected feature IDs */
120
- features: MapFeatureId[];
121
- constructor(type: SelectionEventType, map: FlowCoreMap, sourceIdentifier: MapSourceIdentifier, features: MapFeatureId[]);
122
- }
123
-
124
- type SelectionMode = 'single' | 'multi' | 'none';
125
- /**
126
- * Selection options for a map data source passed to {@link SelectionPlugin.enableSelection}. See {@link SelectionPlugin} for more details.
127
- */
128
- interface SelectionOptions {
129
- /** Clear mode for selection */
130
- clear?: boolean | 'group';
131
- /** Selection group ID - applies when `clear` mode is set to `group`. */
132
- group?: string;
133
- /** Selection mode: `single` or `multi` */
134
- mode: SelectionMode;
135
- /** ID of popup to display when selecting a feature. */
136
- popup?: string;
137
- /** Reactive state property to bind to selection state. */
138
- selectionState?: string;
139
- /** Map data source layer. Note that this is only required for custom vector data sources. */
140
- sourceLayer?: string;
141
- }
142
- /**
143
- * @noInheritDoc
144
- *
145
- * This plugin provides selection functionality allowing a user to select features by clicking the map. It supports single or multiple feature selection, and can
146
- * automatically display popups for selected features.
147
- *
148
- * 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.
149
- *
150
- * **NOTE** To support selection the `featureId` property or the map data source must be defined to allow features to be uniquely identified.
151
- *
152
- * ## Selection Modes
153
- *
154
- * Selection modes can be configured individually for each of a map's data sources. The following modes are supported:
155
- *
156
- * | Mode | Behavior |
157
- * |------|-------------|
158
- * | `none` | Feature selection is disabled for the map data source. (default)|
159
- * |`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. |
160
- * |`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.|
161
- *
162
- * ## Clearing selection
163
- *
164
- * 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.
165
- * 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:
166
- *
167
- * | Clear mode | Behavior |
168
- * |------------|-------------|
169
- * | `false`| Selection state is preserved when selecting features of another map data source. (default) |
170
- * | `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.|
171
- * | `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.|
172
- *
173
- * ## Binding Feature Selection to Reactive State
174
- *
175
- * Setting the {@link SelectionOptions.selectionState} property when configuring selection for a map data source binds the selection state to a reactive state property.
176
- * 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.
177
- *
178
- * 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.
179
- *
180
- * | Selection mode | Reactive binding |
181
- * |------------|-------------|
182
- * | `single` | Single map feature ID (string or number) |
183
- * | `multi` | Array of map feature IDs |
184
- *
185
- * ## Selection events
186
- *
187
- * In addition to supporting binding to reactive state, the plugin also emits a `selectionChanged` event when selection state changes for a map data source.
188
- *
189
- * ## Popups
190
- *
191
- * 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
192
- * and closed when the feature is deselected. Currently, setting the selection state programmatically will not trigger the popup to be displayed.
193
- *
194
- * See (@link PopupPlugin} for more details of how to define and register popups.
195
- *
196
- *
197
- * ## Styling selection state
198
- *
199
- * 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.
200
- *
201
- * @example
202
- * Apply a selection effect using the `circleStrokeWidth` property:
203
- ```js{14}
204
- import { SelectionPlugin } from '@emuanalytics/flow-rdf-core/plugins';
205
- const selectionPlugin = map.getPlugin(SelectionPlugin);
206
-
207
- selectionPlugin.enableSelection("airquality_source", {
208
- mode: "multi"
209
- });
210
-
211
- const circleLayer = new MapLayer({
212
- id: "circle-layer",
213
- type: "circle",
214
- source: "airquality_source",
215
- style: layerStyle("circle")
216
- .circleColor(expr(`@no2 ? from-palette('YlOrRd', @no2, 0, 100) : gray`))
217
- .circleStrokeWidth(expr("@@selected ? 5 : 0"))
218
- .circleRadius(expr(`@no2 ? @no2 / 5 : 5`))
219
- .build()
220
- });
221
- ```
222
- * @example
223
- * Add an event listener for `selectionChanged` events:
224
- ```js
225
- selectionPlugin.on('selectionChanged', (e) => {
226
- console.log(`Selection changed for source: ${e.source}`);
227
- console.log(`Selected features: ${e.features.join(',')}`);
228
- });
229
- ```
230
- */
231
- declare class SelectionPlugin extends MapPluginBase<undefined, SelectionEventTypes> {
232
- private _sourceSelections;
233
- private _enablePopups;
234
- readonly name = "SelectionPlugin";
235
- /**
236
- * Constructs a new SelectionPlugin instance. This is called automatically when the plugin is added to a {@link FlowCoreMap} instance
237
- * using {@link FlowCoreMap.usePlugin} method.
238
- *
239
- * @param pluginManager The plugin manager instance associated with the map
240
- */
241
- constructor(pluginManager: PluginManager);
242
- /**
243
- * Clears selection for the specified map data source.
244
- *
245
- * @param source Map data source ID
246
- */
247
- clearSelection(source: string): void;
248
- /**
249
- * Deselect the specified feature or features.
250
- *
251
- * @param source Map data source ID
252
- * @param features feature ID or array of feature IDs to deselect
253
- */
254
- deselectFeatures(source: string, features: MapFeatureId | MapFeatureId[]): void;
255
- /**
256
- * @internal
257
- */
258
- destroy(): void;
259
- /**
260
- * Disable selection for the specified map data source.
261
- *
262
- * @param source Map data source ID
263
- */
264
- disableSelection(source: string): void;
265
- /**
266
- * Enable selection support for the specified map data source.
267
- *
268
- * @param source Map data source ID
269
- * @param options Selection options
270
- */
271
- enableSelection(source: string, options: SelectionOptions): void;
272
- /**
273
- * @internal
274
- */
275
- handleBeforeSourceRemoved(event: MapSourceEvent): void;
276
- /**
277
- * @internal
278
- */
279
- handleClick(event: MapMouseEvent): void;
280
- /**
281
- * Select the specified feature or features.
282
- *
283
- * Use this method to programmatically select features on a map data source. This will update the selection state and trigger display of
284
- * any associated popups if configured.
285
- *
286
- * @param source Map data source ID
287
- * @param features feature ID or array of feature IDs to select
288
- * @param showPopups Show popups for the selected features. Defaults to `true`.
289
- */
290
- selectFeatures(source: string, features: MapFeatureId | MapFeatureId[], showPopups?: boolean): void;
291
- /**
292
- * Gets the selected feature IDs for the specified map data source.
293
- *
294
- * @param source map data source ID
295
- * @returns Array of selected feature IDs
296
- */
297
- selectedFeatureIds(source: string): MapFeatureId[];
298
- /**
299
- * Returns a {@link MapFeatureStream} of selected features for the specified map data source.
300
- *
301
- * Subscribe to the stream to receive updates when the selection state changes and receive full feature property data
302
- * from the map.
303
- *
304
- * @param source Map data source ID
305
- * @returns {@link MapFeatureStream} of selected features
306
- */
307
- selectedFeatureStream(source: string): MapFeatureStream;
308
- /**
309
- * Enable display of popups when a feature is clicked and an associated popup has been registered with the map data source.
310
- * See {@link PopupPlugin} for more details of how to define and register popups.
311
- *
312
- * Note that popups are enabled by default.
313
- */
314
- enablePopups(): void;
315
- /**
316
- * Disable display of popups when a feature is clicked. This will also close any currently open popups.
317
- */
318
- disablePopups(): void;
319
- featureHasPopup(source: string, featureId: MapFeatureId): boolean;
320
- }
321
-
322
102
  /**
323
103
  * An {@link AnnotationPlugin} operation to support undo/redo functionality. Annotation operations are
324
104
  * stored on the AnnotationPlugin's undo/redo stacks. State to undo and redo operations is captured as closures
@@ -1150,4 +930,253 @@ declare class PopupPlugin extends MapPluginBase {
1150
930
  closePopupsForSources(sources: string | string[]): void;
1151
931
  }
1152
932
 
1153
- 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, type HoverOptions, HoverPlugin, MapPluginBase, PluginManager, PopupPlugin, SelectionEvent, type SelectionEventType, type SelectionEventTypes, type SelectionMode, type SelectionOptions, SelectionPlugin };
933
+ type SelectionEventType = 'selectionChanged';
934
+ interface SelectionEventTypes {
935
+ selectionChanged: (event: SelectionEvent) => void;
936
+ }
937
+ /**
938
+ * This event is emitted by the {@link SelectionPlugin} when selection state changes following user interaction.
939
+ *
940
+ * The event detail indicates which map data source has changed and its currently selected features.
941
+ * An empty `features` array indicates that no features are selected.
942
+ *
943
+ * @group Events
944
+ */
945
+ declare class SelectionEvent extends MapEvent<SelectionEventType> implements MapSourceIdentifier {
946
+ /** Map data source ID */
947
+ source: string;
948
+ /** Map data source layer ID */
949
+ sourceLayer?: string;
950
+ /** Array of selected feature IDs */
951
+ features: MapFeatureId[];
952
+ constructor(type: SelectionEventType, map: FlowCoreMap, sourceIdentifier: MapSourceIdentifier, features: MapFeatureId[]);
953
+ }
954
+
955
+ /**
956
+ * @noInheritDoc
957
+ *
958
+ * This plugin provides selection functionality allowing a user to select features by clicking the map. It supports single or multiple feature selection, and can
959
+ * automatically display popups for selected features.
960
+ *
961
+ * 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, declare them
962
+ * with the data source's {@link flow-rdf-core!MapDataSourceOptions.selection | MapDataSourceOptions.selection} option, or call the {@link enableSelection} method of the plugin.
963
+ *
964
+ * **NOTE** To support selection the `featureId` property or the map data source must be defined to allow features to be uniquely identified.
965
+ *
966
+ * ## Declaring selection on a map data source
967
+ *
968
+ * A map data source added with a `selection` option declares its selection options. The plugin enables selection for each map data source that declares it, both those
969
+ * on the map when the plugin is installed and those added later, so the order of the two doesn't matter.
970
+ *
971
+ * Calling {@link enableSelection} for a map data source replaces its declared options, and {@link disableSelection} turns its selection off, until the data source is added to the map again.
972
+ * A declaration that can't be enabled, such as one with a `popup` when the {@link PopupPlugin} isn't installed, or one on a data source without a `featureId`, is reported
973
+ * through the map's `error` event, and the data source has no selection. Install the {@link PopupPlugin} before this plugin when declared selection options use popups.
974
+ *
975
+ * ## Selection Modes
976
+ *
977
+ * Selection modes can be configured individually for each of a map's data sources. The following modes are supported:
978
+ *
979
+ * | Mode | Behavior |
980
+ * |------|-------------|
981
+ * | `none` | Feature selection is disabled for the map data source. (default)|
982
+ * |`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. |
983
+ * |`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.|
984
+ *
985
+ * ## Clearing selection
986
+ *
987
+ * 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.
988
+ * 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:
989
+ *
990
+ * | Clear mode | Behavior |
991
+ * |------------|-------------|
992
+ * | `false`| Selection state is preserved when selecting features of another map data source. (default) |
993
+ * | `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.|
994
+ * | `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.|
995
+ *
996
+ * ## Binding Feature Selection to Reactive State
997
+ *
998
+ * Setting the {@link SelectionOptions.selectionState} property when configuring selection for a map data source binds the selection state to a reactive state property.
999
+ * 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.
1000
+ *
1001
+ * 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.
1002
+ *
1003
+ * | Selection mode | Reactive binding |
1004
+ * |------------|-------------|
1005
+ * | `single` | Single map feature ID (string or number) |
1006
+ * | `multi` | Array of map feature IDs |
1007
+ *
1008
+ * ## Selection events
1009
+ *
1010
+ * In addition to supporting binding to reactive state, the plugin also emits a `selectionChanged` event when selection state changes for a map data source.
1011
+ *
1012
+ * ## Popups
1013
+ *
1014
+ * 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
1015
+ * and closed when the feature is deselected. Currently, setting the selection state programmatically will not trigger the popup to be displayed.
1016
+ *
1017
+ * See (@link PopupPlugin} for more details of how to define and register popups.
1018
+ *
1019
+ *
1020
+ * ## Styling selection state
1021
+ *
1022
+ * 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.
1023
+ *
1024
+ * @example
1025
+ * Apply a selection effect using the `circleStrokeWidth` property:
1026
+ ```js{14}
1027
+ import { SelectionPlugin } from '@emuanalytics/flow-rdf-core/plugins';
1028
+ const selectionPlugin = map.getPlugin(SelectionPlugin);
1029
+
1030
+ selectionPlugin.enableSelection("airquality_source", {
1031
+ mode: "multi"
1032
+ });
1033
+
1034
+ const circleLayer = new MapLayer({
1035
+ id: "circle-layer",
1036
+ type: "circle",
1037
+ source: "airquality_source",
1038
+ style: layerStyle("circle")
1039
+ .circleColor(expr(`@no2 ? from-palette('YlOrRd', @no2, 0, 100) : gray`))
1040
+ .circleStrokeWidth(expr("@@selected ? 5 : 0"))
1041
+ .circleRadius(expr(`@no2 ? @no2 / 5 : 5`))
1042
+ .build()
1043
+ });
1044
+ ```
1045
+ * @example
1046
+ * Declare selection options on a map data source:
1047
+ ```js
1048
+ map.usePlugin(SelectionPlugin);
1049
+
1050
+ map.addSource({
1051
+ id: "airquality_source",
1052
+ type: "geojson",
1053
+ src: "airquality",
1054
+ featureId: "site_id",
1055
+ selection: { mode: "single", selectionState: "selectedSite" }
1056
+ });
1057
+ ```
1058
+ * @example
1059
+ * Add an event listener for `selectionChanged` events:
1060
+ ```js
1061
+ selectionPlugin.on('selectionChanged', (e) => {
1062
+ console.log(`Selection changed for source: ${e.source}`);
1063
+ console.log(`Selected features: ${e.features.join(',')}`);
1064
+ });
1065
+ ```
1066
+ */
1067
+ declare class SelectionPlugin extends MapPluginBase<undefined, SelectionEventTypes> {
1068
+ private _sourceSelections;
1069
+ /** Data sources whose selection comes from their declared options, which a later declaration replaces */
1070
+ private _declared;
1071
+ private _initialized;
1072
+ private _enablePopups;
1073
+ readonly name = "SelectionPlugin";
1074
+ /**
1075
+ * Constructs a new SelectionPlugin instance. This is called automatically when the plugin is added to a {@link FlowCoreMap} instance
1076
+ * using {@link FlowCoreMap.usePlugin} method.
1077
+ *
1078
+ * @param pluginManager The plugin manager instance associated with the map
1079
+ */
1080
+ constructor(pluginManager: PluginManager);
1081
+ /**
1082
+ * Clears selection for the specified map data source.
1083
+ *
1084
+ * @param source Map data source ID
1085
+ */
1086
+ clearSelection(source: string): void;
1087
+ /**
1088
+ * Deselect the specified feature or features.
1089
+ *
1090
+ * @param source Map data source ID
1091
+ * @param features feature ID or array of feature IDs to deselect
1092
+ */
1093
+ deselectFeatures(source: string, features: MapFeatureId | MapFeatureId[]): void;
1094
+ /**
1095
+ * @internal
1096
+ */
1097
+ destroy(): void;
1098
+ /**
1099
+ * Disable selection for the specified map data source.
1100
+ *
1101
+ * @param source Map data source ID
1102
+ */
1103
+ disableSelection(source: string): void;
1104
+ /**
1105
+ * Enable selection support for the specified map data source. The options replace any that the data source declares
1106
+ * with its {@link flow-rdf-core!MapDataSourceOptions.selection | MapDataSourceOptions.selection} option.
1107
+ *
1108
+ * @param source Map data source ID
1109
+ * @param options Selection options
1110
+ */
1111
+ enableSelection(source: string, options: SelectionOptions): void;
1112
+ /**
1113
+ * @internal
1114
+ */
1115
+ initialize(): void;
1116
+ /**
1117
+ * @internal
1118
+ */
1119
+ handleBeforeSourceRemoved(event: MapSourceEvent): void;
1120
+ /**
1121
+ * @internal
1122
+ */
1123
+ handleSourceAdded(event: MapSourceEvent): void;
1124
+ /**
1125
+ * @internal
1126
+ */
1127
+ handleStyleChanged(): void;
1128
+ /**
1129
+ * @internal
1130
+ */
1131
+ handleClick(event: MapMouseEvent): void;
1132
+ /**
1133
+ * Select the specified feature or features.
1134
+ *
1135
+ * Use this method to programmatically select features on a map data source. This will update the selection state and trigger display of
1136
+ * any associated popups if configured.
1137
+ *
1138
+ * @param source Map data source ID
1139
+ * @param features feature ID or array of feature IDs to select
1140
+ * @param showPopups Show popups for the selected features. Defaults to `true`.
1141
+ */
1142
+ selectFeatures(source: string, features: MapFeatureId | MapFeatureId[], showPopups?: boolean): void;
1143
+ /**
1144
+ * Gets the selected feature IDs for the specified map data source.
1145
+ *
1146
+ * @param source map data source ID
1147
+ * @returns Array of selected feature IDs
1148
+ */
1149
+ selectedFeatureIds(source: string): MapFeatureId[];
1150
+ /**
1151
+ * Returns a {@link MapFeatureStream} of selected features for the specified map data source.
1152
+ *
1153
+ * Subscribe to the stream to receive updates when the selection state changes and receive full feature property data
1154
+ * from the map.
1155
+ *
1156
+ * @param source Map data source ID
1157
+ * @returns {@link MapFeatureStream} of selected features
1158
+ */
1159
+ selectedFeatureStream(source: string): MapFeatureStream;
1160
+ /**
1161
+ * Enable display of popups when a feature is clicked and an associated popup has been registered with the map data source.
1162
+ * See {@link PopupPlugin} for more details of how to define and register popups.
1163
+ *
1164
+ * Note that popups are enabled by default.
1165
+ */
1166
+ enablePopups(): void;
1167
+ /**
1168
+ * Disable display of popups when a feature is clicked. This will also close any currently open popups.
1169
+ */
1170
+ disablePopups(): void;
1171
+ /**
1172
+ * Enables the selection a source declares, or drops a declared selection that it no longer declares. Runs from map
1173
+ * event handlers, so it reports what it can't enable through the map instead of throwing.
1174
+ */
1175
+ private enableDeclaredSelection;
1176
+ /** Why declared selection options can't be enabled, if they can't. */
1177
+ private declarationProblem;
1178
+ private hasPopupPlugin;
1179
+ featureHasPopup(source: string, featureId: MapFeatureId): boolean;
1180
+ }
1181
+
1182
+ 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, type HoverOptions, HoverPlugin, MapPluginBase, PluginManager, PopupPlugin, SelectionEvent, type SelectionEventType, type SelectionEventTypes, SelectionOptions, SelectionPlugin };