@vcmap/core 5.0.0-rc.3 → 5.0.0-rc.30

package/src/category/category.js

@@ -0,0 +1,483 @@
+import { check } from '@vcsuite/check';
+import { v4 as uuidv4 } from 'uuid';
+import { Feature } from 'ol';
+import { moduleIdSymbol, destroyCollection } from '../vcsModuleHelpers.js';
+import makeOverrideCollection, {
+  isOverrideCollection,
+} from '../util/overrideCollection.js';
+import VcsObject from '../vcsObject.js';
+import VectorLayer from '../layer/vectorLayer.js';
+import IndexedCollection from '../util/indexedCollection.js';
+import { parseGeoJSON, writeGeoJSONFeature } from '../layer/geojsonHelpers.js';
+import Collection from '../util/collection.js';
+import { getStyleOrDefaultStyle } from '../style/styleFactory.js';
+import {
+  categoryClassRegistry,
+  getObjectFromClassRegistry,
+} from '../classRegistry.js';
+import OverrideClassRegistry from '../overrideClassRegistry.js';
+import VcsEvent from '../vcsEvent.js';
+
+/**
+ * @typedef {VcsObjectOptions} CategoryOptions
+ * @property {string} [title]
+ * @property {string|symbol} [classRegistryName] - the class registry name on the current app to provide classes for this category. if provided, parseItems will deserialize using this class registry. See: {@link getObjectFromClassRegistry}.
+ * @property {string|undefined} [featureProperty]
+ * @property {VectorOptions} [layerOptions={}]
+ * @property {string} [keyProperty=name]
+ */
+
+/**
+ * @type {*|string}
+ */
+const categoryModuleId = uuidv4();
+
+/**
+ * @param {import("@vcmap/core").VectorLayer} layer
+ * @param {VectorOptions} options
+ * @private
+ */
+function assignLayerOptions(layer, options) {
+  if (options.style) {
+    layer.setStyle(getStyleOrDefaultStyle(options.style, layer.defaultStyle));
+  }
+
+  if (options.highlightStyle) {
+    const highlightStyle = getStyleOrDefaultStyle(
+      options.highlightStyle,
+      layer.highlightStyle,
+    );
+    layer.setHighlightStyle(
+      /** @type {import("@vcmap/core").VectorStyleItem} */ (highlightStyle),
+    );
+  }
+
+  if (options.vectorProperties) {
+    layer.vectorProperties.setValues(options.vectorProperties);
+  }
+
+  if (options.zIndex != null) {
+    layer.zIndex = options.zIndex;
+  }
+}
+
+/**
+ * @param {string} key
+ * @param {T} value
+ * @param {T} defaultOption
+ * @param {T=} option
+ * @template {number|boolean|string|symbol} T
+ * @returns {void}
+ */
+function checkMergeOptionOverride(key, value, defaultOption, option) {
+  const isOverride =
+    option == null ? value !== defaultOption : option !== value;
+  if (isOverride) {
+    throw new Error(`Cannot merge options, values of ${key} do not match`);
+  }
+}
+
+/**
+ * A category contains user based items and is a special container. The container should not be created directly, but via
+ * the requestCategory API on the categories collection. Do not use toJSON to retrieve the state of a category, since
+ * categories outlive modules and may be changed with mergeOptions to no longer reflect your initial state. Requestors
+ * should keep track of the requested options themselves.
+ * @class
+ * @extends {VcsObject}
+ * @template {Object|VcsObject} T
+ */
+class Category extends VcsObject {
+  static get className() {
+    return 'Category';
+  }
+
+  /**
+   * @returns {CategoryOptions}
+   */
+  static getDefaultConfig() {
+    return {
+      title: '',
+      featureProperty: undefined,
+      classRegistryName: undefined,
+      layerOptions: {},
+      keyProperty: 'name',
+    };
+  }
+
+  /**
+   * @param {CategoryOptions} options
+   */
+  constructor(options) {
+    super(options);
+    const defaultOptions = Category.getDefaultConfig();
+    /**
+     * @type {string}
+     */
+    this.title = options.title || this.name;
+    /**
+     * @type {import("@vcmap/core").VcsApp}
+     * @protected
+     */
+    this._app = null;
+    /**
+     * @type {string}
+     * @private
+     */
+    this._featureProperty =
+      options.featureProperty || defaultOptions.featureProperty;
+    /**
+     * @type {string|symbol}
+     * @private
+     */
+    this._classRegistryName = options.classRegistryName;
+    /**
+     * @type {VectorOptions}
+     * @private
+     */
+    this._layerOptions = options.layerOptions || defaultOptions.layerOptions;
+    /**
+     * @type {import("@vcmap/core").VectorLayer}
+     * @protected
+     */
+    this._layer = null;
+    if (this._featureProperty) {
+      this._layer = new VectorLayer(this._layerOptions);
+      this._layer[moduleIdSymbol] = categoryModuleId;
+    }
+    /**
+     * @type {string}
+     * @private
+     */
+    this._keyProperty = options.keyProperty || defaultOptions.keyProperty;
+    /**
+     * Event raised if the collection is reset
+     * @type {VcsEvent<void>}
+     * @private
+     */
+    this._collectionChanged = new VcsEvent();
+    /**
+     * @type {Array<function():void>}
+     * @private
+     */
+    this._collectionListeners = [];
+    /**
+     * @type {OverrideCollection<T>}
+     * @private
+     */
+    this._collection = null;
+    this.setCollection(new IndexedCollection(this._keyProperty));
+    /**
+     * @type {function():void}
+     * @private
+     */
+    this._moduleRemovedListener = () => {};
+  }
+
+  /**
+   * @type {string|symbol}
+   * @readonly
+   */
+  get classRegistryName() {
+    return this._classRegistryName;
+  }
+
+  /**
+   * The collection of this category.
+   * @type {OverrideCollection<T>}
+   * @readonly
+   */
+  get collection() {
+    return this._collection;
+  }
+
+  /**
+   * Event raised if the collection is reset
+   * @type {VcsEvent<void>}
+   * @readonly
+   */
+  get collectionChanged() {
+    return this._collectionChanged;
+  }
+
+  /**
+   * Returns the layer of this collection. Caution, do not use the layer API to add or remove items.
+   * When adding items to the collection, the features are added to the layer async (timeout of 0), since there is weird behavior
+   * when removing and adding a feature with the same id in the same sync call.
+   * @type {import("@vcmap/core").VectorLayer|null}
+   */
+  get layer() {
+    return this._layer;
+  }
+
+  /**
+   * @param {T} item
+   * @protected
+   */
+  _itemAdded(item) {
+    if (this._featureProperty) {
+      const id = item[this._keyProperty];
+      this._layer.removeFeaturesById([id]); // this may be a replacement.
+
+      const geoJsonFeature = item[this._featureProperty];
+      let feature;
+      if (geoJsonFeature instanceof Feature) {
+        feature = geoJsonFeature;
+      } else if (typeof geoJsonFeature === 'object') {
+        const { features } = parseGeoJSON(geoJsonFeature);
+        if (features[0]) {
+          // XXX do we warn on feature collection?
+          feature = features[0];
+        }
+      }
+
+      if (feature) {
+        feature.setId(id);
+        setTimeout(() => {
+          this._layer.addFeatures([feature]);
+        }, 0); // We need to set a timeout, since removing and adding the feature in the same sync call leads to undefined behavior in OL TODO recheck in ol 6.11
+      }
+    }
+  }
+
+  /**
+   * @param {T} item
+   * @protected
+   */
+  _itemRemoved(item) {
+    if (this._featureProperty) {
+      this._layer.removeFeaturesById([item[this._keyProperty]]);
+    }
+  }
+
+  /**
+   * @param {T} item
+   * @protected
+   */
+  // eslint-disable-next-line class-methods-use-this,no-unused-vars
+  _itemReplaced(item) {}
+
+  /**
+   * @param {T} item
+   * @protected
+   */
+  // eslint-disable-next-line class-methods-use-this,no-unused-vars
+  _itemMoved(item) {}
+
+  /**
+   * @returns {string}
+   * @private
+   */
+  _getDynamicModuleId() {
+    if (!this._app) {
+      throw new Error('Cannot get dynamic module id, before setting the vcApp');
+    }
+    return this._app.dynamicModuleId;
+  }
+
+  /**
+   * Throws if typed, featureProperty and keyProperty do not match. Merges other options.
+   * Only merges: style, highlightStyle, zIndex & vectorProperties from layerOptions.
+   * @param {CategoryOptions} options
+   */
+  mergeOptions(options) {
+    const defaultOptions = Category.getDefaultConfig();
+    checkMergeOptionOverride(
+      'classRegistryName',
+      this._classRegistryName,
+      defaultOptions.classRegistryName,
+      options.classRegistryName,
+    );
+    checkMergeOptionOverride(
+      'featureProperty',
+      this._featureProperty,
+      defaultOptions.featureProperty,
+      options.featureProperty,
+    );
+    checkMergeOptionOverride(
+      'keyProperty',
+      this._keyProperty,
+      defaultOptions.keyProperty,
+      options.keyProperty,
+    );
+    this.title = options.title || this.title;
+    if (options.layerOptions && this._layer) {
+      assignLayerOptions(this._layer, options.layerOptions);
+    }
+  }
+
+  /**
+   * When setting the category, it MUST use the same uniqueKey as the previous collection (default is "name").
+   * All items in the current collection _will be destroyed_ and the current collection will be destroyed. The category will take
+   * complete ownership of the collection and destroy it once the category is destroyed. The collection will
+   * be turned into an {@see OverrideCollection}.
+   * @param {import("@vcmap/core").Collection<T>} collection
+   */
+  setCollection(collection) {
+    check(collection, Collection);
+
+    if (this._keyProperty !== collection.uniqueKey) {
+      throw new Error(
+        'The collections key property does not match the categories key property',
+      );
+    }
+
+    this._collectionListeners.forEach((cb) => {
+      cb();
+    });
+    if (this._collection) {
+      destroyCollection(this._collection);
+    }
+    if (this._layer) {
+      this._layer.removeAllFeatures(); // XXX should we call `itemRemoved` instead?
+    }
+
+    this._collection = collection[isOverrideCollection]
+      ? /** @type {OverrideCollection} */ (collection)
+      : makeOverrideCollection(
+          collection,
+          this._getDynamicModuleId.bind(this),
+          this._serializeItem.bind(this),
+          this._deserializeItem.bind(this),
+        );
+
+    [...this.collection].forEach((item) => {
+      this._itemAdded(item);
+    });
+    /**
+     * @type {Array<function():void>}
+     * @private
+     */
+    this._collectionListeners = [
+      this._collection.added.addEventListener(this._itemAdded.bind(this)),
+      this._collection.removed.addEventListener(this._itemRemoved.bind(this)),
+      this._collection.replaced.addEventListener(this._itemReplaced.bind(this)),
+    ];
+
+    // @ts-ignore
+    if (this._collection.moved) {
+      this._collectionListeners.push(
+        // @ts-ignore
+        this._collection.moved.addEventListener(this._itemMoved.bind(this)),
+      );
+    }
+    this.collectionChanged.raiseEvent();
+  }
+
+  /**
+   * @param {import("@vcmap/core").VcsApp} app
+   */
+  setApp(app) {
+    if (this._app) {
+      throw new Error('Cannot switch apps');
+    }
+    this._app = app;
+    this._moduleRemovedListener = this._app.moduleRemoved.addEventListener(
+      (module) => {
+        this._collection.removeModule(module._id);
+      },
+    );
+    if (this._layer) {
+      this._app.layers.add(this._layer);
+    }
+  }
+
+  /**
+   * @protected
+   * @param {*} config
+   * @returns {Promise<T>} // XXX should this still be async?
+   */
+  async _deserializeItem(config) {
+    if (!this._app) {
+      throw new Error('Cannot deserialize item before setting the vcApp');
+    }
+    const classRegistry = this._classRegistryName
+      ? this._app[this._classRegistryName]
+      : null;
+    if (classRegistry && classRegistry instanceof OverrideClassRegistry) {
+      return getObjectFromClassRegistry(classRegistry, config);
+    }
+    return config;
+  }
+
+  /**
+   * @protected
+   * @param {T} item
+   * @returns {Object}
+   */
+  _serializeItem(item) {
+    const config = JSON.parse(JSON.stringify(item));
+    if (this._featureProperty) {
+      const feature = this._layer.getFeatureById(item[this._keyProperty]);
+      if (feature) {
+        config[this._featureProperty] = writeGeoJSONFeature(feature);
+      }
+    }
+    return config;
+  }
+
+  /**
+   * @param {string} moduleId
+   * @returns {{ name: string, items: Array<Object>}|null}
+   */
+  serializeModule(moduleId) {
+    if (this._collection.size === 0) {
+      return null;
+    }
+
+    return {
+      name: this.name,
+      items: this.collection.serializeModule(moduleId),
+    };
+  }
+
+  /**
+   * @returns {CategoryOptions}
+   */
+  toJSON() {
+    const config = /** @type {CategoryOptions} */ (super.toJSON());
+
+    const defaultOptions = Category.getDefaultConfig();
+    if (this.title !== this.name) {
+      config.title = this.title;
+    }
+    if (this._featureProperty !== defaultOptions.featureProperty) {
+      config.featureProperty = this._featureProperty;
+    }
+    if (this._classRegistryName !== defaultOptions.classRegistryName) {
+      config.classRegistryName = this._classRegistryName;
+    }
+    if (Object.keys(this._layerOptions).length > 0) {
+      config.layerOptions = { ...this._layerOptions };
+    }
+    if (this._keyProperty !== defaultOptions.keyProperty) {
+      config.keyProperty = this._keyProperty;
+    }
+    return config;
+  }
+
+  /**
+   * @inheritDoc
+   */
+  destroy() {
+    super.destroy();
+    if (this._app && this._layer) {
+      this._app.layers.remove(this._layer);
+    }
+    if (this._layer) {
+      this._layer.destroy();
+    }
+
+    this._collectionListeners.forEach((cb) => {
+      cb();
+    });
+    this._collectionListeners.splice(0);
+    this._moduleRemovedListener();
+    this._moduleRemovedListener = () => {};
+    destroyCollection(this._collection);
+    this._collectionChanged.destroy();
+    this._app = null;
+  }
+}
+
+export default Category;
+categoryClassRegistry.registerClass(Category.className, Category);

package/src/category/categoryCollection.js

@@ -0,0 +1,153 @@
+import { getLogger as getLoggerByName } from '@vcsuite/logger';
+import Category from './category.js';
+import IndexedCollection from '../util/indexedCollection.js';
+import { getObjectFromClassRegistry } from '../classRegistry.js';
+
+/**
+ * @returns {import("@vcsuite/logger").Logger}
+ */
+function getLogger() {
+  return getLoggerByName('CategoryCollection');
+}
+
+/**
+ * @class
+ * @extends {IndexedCollection<Category<Object|import("@vcmap/core").VcsObject>>}
+ */
+class CategoryCollection extends IndexedCollection {
+  /**
+   * @param {import("@vcmap/core").VcsApp} app
+   */
+  constructor(app) {
+    super();
+    /**
+     * @type {import("@vcmap/core").VcsApp}
+     * @private
+     */
+    this._app = app;
+    /**
+     * Map of category names, where the value is a map of moduleId and items.
+     * @type {Map<string, Map<string, Array<Object>>>}
+     * @private
+     */
+    this._cache = new Map();
+    /**
+     * @type {Function}
+     * @private
+     */
+    this._moduleRemovedListener = this._app.moduleRemoved.addEventListener(
+      (module) => {
+        this._cache.forEach((moduleMap, name) => {
+          moduleMap.delete(module._id);
+          if (moduleMap.size === 0) {
+            this._cache.delete(name);
+          }
+        });
+      },
+    );
+  }
+
+  /**
+   * Do not call add directly. Use request category for adding categories.
+   * @param {Category<Object|import("@vcmap/core").VcsObject>} category
+   * @returns {number|null}
+   */
+  add(category) {
+    // XXX use a symbol to enforce using request over add?
+    if (this.hasKey(category.name)) {
+      return null;
+    }
+
+    category.setApp(this._app);
+    const added = super.add(category);
+    if (added != null && this._cache.has(category.name)) {
+      this._cache.get(category.name).forEach((items, moduleId) => {
+        this.parseCategoryItems(category.name, items, moduleId);
+      });
+
+      this._cache.delete(category.name);
+    }
+    return added;
+  }
+
+  /**
+   * Categories should be static. Removing them can lead to undefined behavior.
+   * @param {Category<Object|import("@vcmap/core").VcsObject>} category
+   */
+  remove(category) {
+    // XXX add logger warning?
+    super.remove(category);
+    this._cache.delete(category.name);
+  }
+
+  /**
+   * Parses the category items. Items will only be parsed, if a category with said name exists. Otherwise,
+   * they will be cached, until such a category is requested.
+   * @param {string} name
+   * @param {Array<Object>} items
+   * @param {string} moduleId
+   * @returns {Promise<void>}
+   */
+  async parseCategoryItems(name, items, moduleId) {
+    const category = this.getByKey(name);
+
+    if (category) {
+      await category.collection.parseItems(items, moduleId);
+    } else if (this._cache.has(name)) {
+      this._cache.get(name).set(moduleId, items);
+    } else {
+      this._cache.set(name, new Map([[moduleId, items]]));
+    }
+  }
+
+  /**
+   * Add categories with this API.
+   * @param {CategoryOptions} options
+   * @returns {Promise<Category<Object|import("@vcmap/core").VcsObject>>}
+   */
+  async requestCategory(options) {
+    if (!options.name) {
+      getLogger().error('Cannot request a category without a name');
+      return null;
+    }
+
+    if (!options.type) {
+      getLogger().warning(
+        `Implicitly typing category ${options.name} as ${Category.className}`,
+      );
+      options.type = Category.className;
+    }
+
+    let category;
+    if (this.hasKey(options.name)) {
+      category = this.getByKey(options.name);
+      category.mergeOptions(options);
+    } else {
+      category = await getObjectFromClassRegistry(
+        this._app.categoryClassRegistry,
+        options,
+      );
+      if (category) {
+        if (this.add(category) == null) {
+          return null;
+        }
+      }
+    }
+
+    if (!category) {
+      throw new Error(
+        `Category ${options.name} with type ${options.type} could not be created`,
+      );
+    }
+    return category;
+  }
+
+  destroy() {
+    super.destroy();
+    this._moduleRemovedListener();
+    this._cache.clear();
+    this._app = null;
+  }
+}
+
+export default CategoryCollection;

package/src/cesium/cesium3DTileFeature.js

@@ -1,9 +1,9 @@
 // @ts-nocheck
-import { Cesium3DTileFeature } from '@vcmap/cesium';
+import { Cesium3DTileFeature } from '@vcmap-cesium/engine';
 
 /**
  * @returns {string|number}
  */
 Cesium3DTileFeature.prototype.getId = function getId() {
-  return this.getProperty('id') || `${this.content.url}${this._batchId}`;
+  return this.getProperty('id') || `${this.content.url}${this._batchId}`; // XXX there is a new property `featureId` on the Cesium3DTileset. this may cause issues when picking b3dm.
 };

package/src/cesium/cesium3DTilePointFeature.js

@@ -1,5 +1,5 @@
 // @ts-nocheck
-import { Cesium3DTilePointFeature } from '@vcmap/cesium';
+import { Cesium3DTilePointFeature } from '@vcmap-cesium/engine';
 
 /**
  * @returns {string|number}