Skip to content

armgit / core

Public Imported from GitHub
0

100% open-source IoT Platform - Integrate your devices, add intelligence, build custom apps

19.4 KB
Raw Blame
/*
 * Copyright 2026, OpenRemote Inc.
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Affero General Public License as
 * published by the Free Software Foundation, either version 3 of the
 * License, or (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU Affero General Public License for more details.
 *
 * You should have received a copy of the GNU Affero General Public License
 * along with this program. If not, see <https://www.gnu.org/licenses/>.
 *
 * SPDX-License-Identifier: AGPL-3.0-or-later
 */
import {
  type CircleLayerSpecification,
  type GeoJSONFeature,
  type GeoJSONSource,
  type MapSourceDataEvent,
  Marker,
} from "maplibre-gl";
import type { Feature, Point } from "geojson";
import type { AssetWithLocation, ClusterConfig, MapFilter } from "./types";
import { BaseMap } from "./base-map";
import { OrClusterMarker, type Slice } from "./markers/or-cluster-marker";
import { getMarkerIconAndColorFromAssetType } from "./util";
import { OrMapLoadedEvent, OrMapMarkersChangedEvent } from ".";
import { Util } from "@openremote/core";
import { type AssetQuery, type AttributeEvent, WellknownAttributes } from "@openremote/model";
import { OrMapLegendControl, OrMapLegendEvent } from "./controls/legend";
import { OrMapPresetFilterControl, OrMapPresetFilterEvent } from "./controls/preset-filter";

type IdentifiableAsset = AssetWithLocation & { id: string; type: string };

/**
 * This class handles where to display asset markers and clusters on the map.
 *
 * Currently, the standard flow to display assets as markers on the map goes as follows:
 *
 * 1. The map page adds assets to the {@link AssetMap}, which computes assets in view and then dispatches {@link OrMapMarkersChangedEvent}.
 * 2. The map page receives the event, renders the received assets as {@link OrMapMarkerAsset} by including them inside the map element's HTML body.
 * 3. The map component then receives either an event from the {@link OrMapMarkerAsset},
 * or when the map component sees a slotted {@link OrMapMarker} was added. From there the {@link OrMapMarker}s are passed to the {@link BaseMap} to be assigned to a MapLibre marker.
 *
 * @todo consider using `this._map.setGlobalStateProperty` for static cluster property
 */
export class AssetMap extends BaseMap {
  private static _clusterProperty = "assetType";

  // All assets ever added — source of truth for filtering and control counts
  private _allAssets: Record<string, AssetWithLocation> = {};
  // Assets currently rendered in the GeoJSON source (visible subset)
  protected _assets: Record<string, AssetWithLocation | null> = {};
  protected _assetTypeColors: Record<string, string> = {};
  protected _assetsOnScreen: Record<string, AssetWithLocation> = {};
  protected _cachedClusters: Record<string, Marker> = {};
  protected _clustersOnScreen: Record<string, Marker> = {};
  protected _clusterConfig?: ClusterConfig;
  protected _source?: GeoJSONSource;

  // Filter / legend state
  private _hostElement: HTMLElement;
  private _filters?: MapFilter[];
  private _showLegend: boolean;
  private _activeFilter: AssetQuery | null = null;
  private _excludedTypes: string[] = [];
  private _allAssetTypes: string[] = [];
  private _allAssetCounts: Record<string, number> = {};
  private _presetFilterControl?: OrMapPresetFilterControl;
  private _legendControl?: OrMapLegendControl;

  // Stable event handler refs so they can be removed on cleanup
  private _onPresetFilter = (e: Event) => {
    this._activeFilter = (e as OrMapPresetFilterEvent).detail;
    this._applyVisibilityFilters();
  };

  private _onLegendChange = (e: Event) => {
    this._excludedTypes = (e as OrMapLegendEvent).detail;
    this._applyVisibilityFilters();
  };

  protected _onMove = () => this._updateMarkers();
  protected _onMoveEnd = (e: any) => {
    // Ensure marker updates happen after the frame
    requestAnimationFrame(() => {
      // The clicked marker may not be removed,
      // if the camera zoom level is directly between 2 levels
      if (e.marker instanceof OrClusterMarker) {
        this._clustersOnScreen[e.marker._clusterId]?.remove();
      }
      this._updateMarkers();
    });
  };

  protected _onData = (e: MapSourceDataEvent) => {
    if (this._map && e.isSourceLoaded && e.sourceId === "assets") {
      this._map.on("move", this._onMove);
      this._map.on("moveend", this._onMoveEnd);
      this._updateMarkers();
    }
  };

  constructor(
    styleParent: Node,
    mapContainer: HTMLElement,
    hostElement: HTMLElement,
    showGeoCodingControl = false,
    showBoundaryBox = false,
    useZoomControls = true,
    showGeoJson = true,
    clusterConfig?: ClusterConfig,
    filters?: MapFilter[],
    showLegend = true
  ) {
    super(styleParent, mapContainer, showGeoCodingControl, showBoundaryBox, useZoomControls, showGeoJson);
    this._clusterConfig = clusterConfig;
    this._hostElement = hostElement;
    this._filters = filters;
    this._showLegend = showLegend;
  }

  override async build(): Promise<void> {
    return super.build().then(() => {
      this._map?.on("load", async () => await this.load());
    });
  }

  // ── Public asset API (filter-aware) ──────────────────────────────────────

  public addAsset(asset: AssetWithLocation) {
    if (!asset.id) return;
    this._allAssets[asset.id] = asset;
    this._syncAssetMeta();
    if (this._presetFilterControl) this._presetFilterControl.assets = Object.values(this._allAssets);
    this._sourceAddAsset(asset);
  }

  public addAssets(assets: AssetWithLocation[]) {
    for (const asset of assets) if (asset.id) this._allAssets[asset.id] = asset;
    this._syncAssetMeta();
    if (this._presetFilterControl) this._presetFilterControl.assets = Object.values(this._allAssets);
    this._sourceAddAssets(assets);
  }

  public updateAttribute(event: AttributeEvent) {
    const id = event?.ref?.id;
    if (!id) return;

    if (this._allAssets[id]) {
      this._allAssets[id] = Util.updateAsset(structuredClone(this._allAssets[id]), event);
      if (this._presetFilterControl) this._presetFilterControl.assets = Object.values(this._allAssets);
    }

    // Update the GeoJSON source if the asset is currently visible
    if (!this._source || !this._assets[id]) return;

    if (event.value == null && event.ref?.name === WellknownAttributes.LOCATION) {
      this._assets[id] = null;
      this._source.updateData({ remove: [id] });
      return;
    }

    const asset = (this._assets[id] = Util.updateAsset(structuredClone(this._assets[id]), event));
    const newGeometry = asset.attributes.location.value;
    const newProperties = Object.entries(AssetMap._assetToFeature(asset as IdentifiableAsset).properties).map(
      ([key, value]) => ({ key, value })
    );
    this._source.updateData({ update: [{ id, newGeometry, addOrUpdateProperties: newProperties }] });
  }

  public removeAssets(ids: string[]) {
    for (const id of ids) delete this._allAssets[id];
    this._syncAssetMeta();
    if (this._presetFilterControl) this._presetFilterControl.assets = Object.values(this._allAssets);
    for (const id of ids) this._assets[id] = null;
    this._source?.updateData({ remove: ids });
  }

  public removeAllAssets() {
    this._allAssets = {};
    this._allAssetTypes = [];
    this._allAssetCounts = {};
    this._activeFilter = null;
    this._excludedTypes = [];
    this._hostElement.classList.remove("has-legend");
    this._legendControl?.clear();
    this._presetFilterControl?.clear();
    this._assets = {};
    this._source?.updateData({ removeAll: true });
  }

  // ── Dynamic control updates ───────────────────────────────────────────────

  public setFilters(filters: MapFilter[] | undefined) {
    this._filters = filters;
    if (!this._loaded) return;
    if (this._presetFilterControl) {
      this._map?.removeControl(this._presetFilterControl);
      this._presetFilterControl = undefined;
    }
    if (filters?.length) {
      this._presetFilterControl = new OrMapPresetFilterControl(filters, Object.values(this._allAssets));
      this._activeFilter = this._presetFilterControl.getInitialFilter();
      this._map?.addControl(this._presetFilterControl, "top-left");
    } else {
      this._activeFilter = null;
    }
    this._hostElement.classList.toggle("has-filters", Boolean(filters?.length));
    this._applyVisibilityFilters();
  }

  public setShowLegend(showLegend: boolean) {
    this._showLegend = showLegend;
    if (!this._loaded) return;
    if (!showLegend && this._legendControl) {
      this._map?.removeControl(this._legendControl);
      this._legendControl = undefined;
    } else if (showLegend && !this._legendControl) {
      this._legendControl = new OrMapLegendControl(this._allAssetTypes, this._excludedTypes, this._allAssetCounts);
      this._map?.addControl(this._legendControl, "bottom-right");
    }
    this._syncAssetMeta();
  }

  // ── Source-level helpers (operate on _assets / GeoJSON source only) ───────

  private _sourceAddAsset(asset: AssetWithLocation) {
    if (!this._source) return;
    const features = this._map!.querySourceFeatures("assets");
    if (!this._hasRequired(asset) || !this._isAssetVisible(asset) || !this._isMissing(asset, features)) return;
    if (this._addAssetType(asset.type)) this._updateClusterProperties(this._source);
    this._assets[asset.id] = asset;
    this._source.updateData({ add: [AssetMap._assetToFeature(asset)] });
  }

  private _sourceAddAssets(assets: AssetWithLocation[]) {
    if (!this._source) return;
    const features = this._map!.querySourceFeatures("assets");
    let missing = assets.filter(this._hasRequired).filter((a) => this._isAssetVisible(a));
    if (features?.length) missing = missing.filter((a) => this._isMissing(a, features));
    if (!missing.length) return;
    let newTypes = false;
    for (const asset of missing) {
      newTypes = this._addAssetType(asset.type) || newTypes;
      this._assets[asset.id] = asset;
    }
    if (newTypes) this._updateClusterProperties(this._source);
    this._source.updateData({ add: missing.map(AssetMap._assetToFeature) });
  }

  // ── Filter / legend internals ─────────────────────────────────────────────

  private _syncAssetMeta() {
    const counts: Record<string, number> = {};
    for (const id in this._allAssets) {
      const type: string | undefined = this._allAssets[id]?.type;
      if (type !== undefined && type !== "") counts[type] = (counts[type] ?? 0) + 1;
    }
    const types = Object.keys(counts);
    this._allAssetTypes = types;
    this._allAssetCounts = counts;
    this._hostElement.classList.toggle("has-legend", this._showLegend && types.length >= 2);
    this._legendControl?.update(types, counts);
  }

  private _isAssetVisible(asset: AssetWithLocation): boolean {
    if (this._activeFilter && !new Util.AssetQueryHelper(this._activeFilter).matches(asset)) return false;
    if (!asset.type) return true;
    return !this._excludedTypes.includes(asset.type);
  }

  private _applyVisibilityFilters() {
    if (!this._source) return;

    const toRemove: string[] = [];
    const toAdd: IdentifiableAsset[] = [];
    let newTypes = false;

    for (const id in this._assets) {
      if (this._assets[id] && !this._isAssetVisible(this._assets[id]!)) {
        this._assets[id] = null;
        toRemove.push(id);
      }
    }

    for (const id in this._allAssets) {
      const asset = this._allAssets[id];
      if (!asset || !this._hasRequired(asset) || this._assets[id]) continue;
      if (this._isAssetVisible(asset)) {
        const a = asset as IdentifiableAsset;
        newTypes = this._addAssetType(a.type) || newTypes;
        this._assets[a.id] = a;
        toAdd.push(a);
      }
    }

    if (!toRemove.length && !toAdd.length) return;

    if (newTypes) this._updateClusterProperties(this._source);
    this._source.updateData({
      ...(toRemove.length && { remove: toRemove }),
      ...(toAdd.length && { add: toAdd.map(AssetMap._assetToFeature) }),
    });
  }

  public override unload() {
    this._mapContainer.removeEventListener(OrMapPresetFilterEvent.NAME, this._onPresetFilter);
    this._mapContainer.removeEventListener(OrMapLegendEvent.NAME, this._onLegendChange);
    super.unload();
  }

  // ── Map lifecycle ─────────────────────────────────────────────────────────

  private async load() {
    if (!this._map || this._loaded) return;

    if (this._map.getSource("assets")) {
      if (this._map.getLayer("asset")) this._map.removeLayer("asset");
      if (this._map.getLayer("cluster")) this._map.removeLayer("cluster");
      this._map.removeSource("assets");
    }

    const baseLayer: Omit<CircleLayerSpecification, "id"> = {
      type: "circle",
      source: "assets",
      paint: { "circle-radius": 0 },
    };

    this._map
      .addSource("assets", {
        type: "geojson",
        cluster: this._clusterConfig?.cluster ?? true,
        clusterRadius: this._clusterConfig?.clusterRadius ?? 180,
        clusterMaxZoom: this._clusterConfig?.clusterMaxZoom ?? 17,
        clusterProperties: this._getClusterProperties(),
        promoteId: "id", // Promote the id property as feature id
        data: { type: "FeatureCollection", features: [] }, // TODO: consider preloading data to avoid tile cache misses
      })
      .addLayer({ ...baseLayer, id: "cluster", filter: ["has", "point_count"] })
      .addLayer({ ...baseLayer, id: "asset", filter: ["!", ["has", "point_count"]] });

    this._source = this._map.getSource("assets") as GeoJSONSource;

    this._map.on("sourcedata", this._onData);

    // Create asset-specific controls
    if (this._filters?.length) {
      this._presetFilterControl = new OrMapPresetFilterControl(this._filters, Object.values(this._allAssets));
      this._map?.addControl(this._presetFilterControl, "top-left");
    }
    if (this._showLegend) {
      this._legendControl = new OrMapLegendControl(this._allAssetTypes, this._excludedTypes, this._allAssetCounts);
      this._map?.addControl(this._legendControl, "bottom-right");
    }
    this._hostElement.classList.toggle("has-filters", Boolean(this._filters?.length));
    this._hostElement.classList.toggle("has-legend", this._showLegend && this._allAssetTypes.length >= 2);

    // Listen for filter/legend events from the controls (bubble through _mapContainer)
    this._mapContainer.addEventListener(OrMapPresetFilterEvent.NAME, this._onPresetFilter);
    this._mapContainer.addEventListener(OrMapLegendEvent.NAME, this._onLegendChange);

    // Restore the active filter synchronously so the buffer flush below applies it immediately,
    // preventing _applyVisibilityFilters from needing to removeAll + re-add after load.
    if (this._presetFilterControl) this._activeFilter = this._presetFilterControl.getInitialFilter();

    // Flush assets that were added before the source was ready
    const buffered = Object.values(this._allAssets);
    if (buffered.length) this._sourceAddAssets(buffered);

    this._mapContainer.dispatchEvent(new OrMapLoadedEvent());
    this._loaded = true;
  }

  protected _updateMarkers() {
    if (!this._map) return;
    const features = this._map.querySourceFeatures("assets");
    const newAssets = this._updateAssets(features);
    this._updateClusters(features);
    this._mapContainer.dispatchEvent(new OrMapMarkersChangedEvent(newAssets));
  }

  private _updateAssets(features: GeoJSONFeature[]) {
    const newAssets: Record<string, AssetWithLocation> = {};

    for (const feature of features) {
      if (!feature.properties.id) continue;
      const id = feature.properties.id as string;
      if (this._assets[id]) newAssets[id] = this._assets[id];
    }

    for (const id in this._assetsOnScreen) {
      if (!newAssets[id]) delete this._assetsOnScreen[id];
    }

    this._assetsOnScreen = newAssets;
    return Object.values(this._assetsOnScreen);
  }

  private _updateClusters(features: GeoJSONFeature[]) {
    const newClusters: Record<string, Marker> = {};

    // Create missing cluster markers
    for (const feature of features) {
      if (!feature.properties.cluster) continue;
      const id: number = feature.properties.cluster_id;
      let marker = this._cachedClusters[id] ?? this._getClusterMarker(feature);
      // Invalidate the cached cluster marker if the type counts don't match
      // If a new type is added, the marker will have a different cluster_id
      if (marker._element instanceof OrClusterMarker && !marker._element.slicesMatch(feature.properties)) {
        marker.remove();
        marker = this._getClusterMarker(feature).addTo(this._map!);
      }
      newClusters[id] = marker;
      // Add the new cluster marker if it's not already on screen
      if (!this._clustersOnScreen[id]) marker.addTo(this._map!);
    }

    // Cleanup clusters that should no longer be on screen
    for (const id in this._clustersOnScreen) {
      if (!newClusters[id]) this._clustersOnScreen[id]?.remove();
    }
    this._clustersOnScreen = newClusters;
  }

  private _getClusterMarker(feature: GeoJSONFeature) {
    const id: number = feature.properties.cluster_id;
    const geometry = feature.geometry as Point;
    const [lng, lat] = geometry.coordinates;

    const slices: Slice[] = Object.entries(feature.properties)
      .filter(([k]) => k in this._assetTypeColors)
      .map(([type, count]) => [type, this._assetTypeColors[type], count]);

    return (this._cachedClusters[id] = new Marker({
      element: new OrClusterMarker(slices, id, lng, lat, this._map!),
    }).setLngLat([lng, lat]));
  }

  private _hasRequired(asset: AssetWithLocation): asset is IdentifiableAsset {
    return Boolean(asset?.id && asset?.type);
  }

  private _isMissing(asset: IdentifiableAsset, features: Feature[]) {
    return !features?.some((f) => f.properties?.id === asset.id);
  }

  private _getClusterProperties() {
    return Object.fromEntries(Object.keys(this._assetTypeColors).map(AssetMap._getClusterPropertyExpression));
  }

  /**
   * Registers the colour of an asset type the map has not seen before
   * @returns Whether the type is new, meaning the cluster properties are out of date
   */
  private _addAssetType(type: string) {
    if (type in this._assetTypeColors) return false;
    this._assetTypeColors[type] = getMarkerIconAndColorFromAssetType(type)?.color as string;
    return true;
  }

  private _updateClusterProperties(source: GeoJSONSource) {
    source.workerOptions.clusterProperties = this._getClusterProperties();
    // Data updates keep the existing cluster index, only a cluster options update rebuilds it with new properties
    const { cluster } = source.getClusterOptions();
    if (cluster) source.setClusterOptions({ cluster });
  }

  private static _getClusterPropertyExpression(value: string) {
    return [value, ["+", ["case", ["==", ["get", AssetMap._clusterProperty], value], 1, 0]]];
  }

  private static _assetToFeature({
    id,
    type,
    name,
    attributes,
  }: IdentifiableAsset): Feature<Point, { id: string; name?: string; [AssetMap._clusterProperty]: string }> {
    return {
      type: "Feature",
      geometry: attributes.location.value,
      properties: { id, name, [AssetMap._clusterProperty]: type },
    };
  }
}