@open-pioneer/map 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,140 @@
 # @open-pioneer/map
 
+## 0.8.0
+
+### Minor Changes
+
+-   b717121: Update from OL 9 to OL 10.
+-   e7978a8: **Breaking:** Remove most events from the map model and the layer interfaces.
+    All events that were merely used to synchronized state (e.g. `changed:title` etc.) have been removed.
+
+    The map model and related objects (layers, layer collections, etc.) are now based on the [Reactivity API](https://github.com/conterra/reactivity/blob/main/packages/reactivity-core/README.md).
+    This change greatly simplifies the code that is necessary to access up-to-date values and to react to changes.
+
+    For example, from inside a React component, you can now write:
+
+    ```jsx
+    import { useReactiveSnapshot } from "@open-pioneer/reactivity";
+
+    function YourComponent() {
+        // Always up to date, even if the layer's title changes.
+        // No more need to listen to events.
+        const title = useReactiveSnapshot(() => layer.title, [layer]);
+        return <div>{title}</div>;
+    }
+    ```
+
+    And inside a normal JavaScript function, you can watch for changes like this:
+
+    ```js
+    import { watch } from "@conterra/reactivity-core";
+
+    const watchHandle = watch(
+        () => [layer.title],
+        ([newTitle]) => {
+            console.log("The title changed to", newTitle);
+        }
+    );
+
+    // Later, cleanup:
+    watchHandle.destroy();
+    ```
+
+    For more details, check the [Reactivity API documentation](https://github.com/conterra/reactivity/blob/main/packages/reactivity-core/README.md).
+
+-   7ae9f90: Add new `children` property to all layers.
+    This property makes it possible to handle any layer children in a generic fashion, regardless of the layer's actual type.
+
+    `layer.children` is either an alias of `layer.sublayers` (if the layer has sublayers), `layer.layers` (if it's a `GroupLayer`) or undefined, if the layer does not have any children.
+
+-   d8337a6: The following hooks are deprecated and will be removed in a future release:
+
+    -   `useView`
+    -   `useProjection`
+    -   `useResolution`
+    -   `useCenter`
+    -   `useScale`
+
+    They can all be replaced by using the new reactive properties on the `MapModel`, for example:
+
+    ```javascript
+    // old:
+    const center = useCenter(olMap);
+
+    // new:
+    const center = useReactiveSnapshot(() => mapModel.center, [mapModel]);
+    ```
+
+-   2fa8020: Update trails core package dependencies.
+
+    -   Also updates Chakra UI to the latest 2.x version and Chakra React Select to version 5.
+    -   Removes any obsolete references to `@chakra-ui/system`.
+        This dependency seems to be no longer required and may lead to duplicate packages in your dependency tree.
+
+-   7ae9f90: Add new layer type `GroupLayer` to to the Map API.
+
+    A `GroupLayer` contains a list of `Layer` (e.g. `SimpleLayer` or `WMSLayer`). Because `GroupLayer` is a `Layer` as well nested groups are supported.
+    The child layers of a `GroupLayer` can be accessed with the `layers` property - `layers` is `undefined` if it is not a group.
+    The parent `GroupLayer` of a child layer can be accessed with the `parent` property - `parent` is `undefined` if this layer is not part of a group (or not a sublayer).
+
+    ```js
+    const olLayer1 = new TileLayer({
+        source: new OSM()
+    });
+    const olLayer2 = new TileLayer({
+        source: new BkgTopPlusOpen()
+    });
+
+    // Create group layer with nested sub group
+    const group = new GroupLayer({
+        id: "group",
+        title: "a group layer",
+        layers: [
+            new SimpleLayer({
+                id: "member",
+                title: "group member",
+                olLayer: olLayer1
+            }),
+            new GroupLayer({
+                id: "subgroup",
+                title: "a nested group layer",
+                layers: [
+                    new SimpleLayer({
+                        id: "submember",
+                        title: "subgroup member",
+                        olLayer: olLayer2
+                    })
+                ]
+            })
+        ]
+    });
+
+    const childLayers: GroupLayerCollection = group.layers; // Access child layers
+    ```
+
+    Layers can only be added to a single group or map.
+    Sublayers (e.g. `WMSSublayer`) cannot be added to a group directly.
+
+-   d8337a6: Provide new reactive properties on the `MapModel` type.
+
+    -   `olView` (-> `olMap.getView()`)
+    -   `projection` (-> `olMap.getView().getProjection()`)
+    -   `resolution` (-> `olMap.getView().getResolution()`)
+    -   `zoomLevel` (-> `olMap.getView().getZoom()`)
+    -   `center` (-> `olMap.getView().getCenter()`)
+    -   `scale` (derived from center and resolution)
+
+    Most of the listed properties are already available on raw OpenLayers objects (see code in parentheses above).
+    However, those OpenLayers properties require manual work for synchronization, whereas the new properties are reactive (and can be watched, for example, using `useReactiveSnapshot()`).
+
+    A new method `setScale()` has also been added to the model.
+
+### Patch Changes
+
+-   7a5f1e1: Fix keyboard events from map anchors after update to OpenLayers 10.
+-   49f0207: Update trails core packages to version 2.4.0
+-   b2127df: Improve documentation of layers in README
+
 ## 0.7.0
 
 ### Minor Changes

package/README.md

@@ -7,8 +7,8 @@ APIs provided by this package can be used to configure, embed and access the map
 
 To use the map in your app, follow these two steps:
 
--   Add a `MapContainer` component to your app (see [Map container component](#md:map-container-component)).
--   Implement a `MapConfigProvider` (see [Map configuration](#md:map-configuration)).
+-   Add a `MapContainer` component to your app (see [Map container component](#map-container-component)).
+-   Implement a `MapConfigProvider` (see [Map configuration](#map-configuration)).
 
 To access or manipulate the content of the map programmatically, see [Using the map model](#using-the-map-model).
 
@@ -36,7 +36,7 @@ function AppUI() {
 }
 ```
 
-> NOTE: There must be a `map.MapConfigProvider` that knows how to construct the map with the given ID (see [Map configuration](#md:map-configuration)).
+> NOTE: There must be a `map.MapConfigProvider` that knows how to construct the map with the given ID (see [Map configuration](#map-configuration)).
 
 The component itself uses the map registry service to create the map using the provided `mapId`.
 
@@ -201,7 +201,7 @@ export class MapConfigProviderImpl implements MapConfigProvider {
 
 #### Layer configuration
 
-Configure your custom layer inside the [Map configuration](#md:map-configuration) by using one of the layer classes provided by this package.
+Configure your custom layer inside the [Map configuration](#map-configuration) by using one of the layer classes provided by this package.
 For example, `SimpleLayer` can be used to configure an arbitrary [`OpenLayers Layer`](https://openlayers.org/en/latest/apidoc/module-ol_layer_Layer-Layer.html) as `olLayer` property.
 
 > **Layer Order**
@@ -621,6 +621,47 @@ export class MapConfigProviderImpl implements MapConfigProvider {
 }
 ```
 
+##### GroupLayer
+
+A `GroupLayer` contains a list of layers (e.g. `SimpleLayer`, `WMSLayer` or nested `GroupLayer`).
+The visibility of all layers within the group is controlled via the parent group layer(s).
+The hierarchy of the layers, which results from the (nested) groups, is rendered accordingly in the table of contents.
+
+Example: Create (nested) group layers
+
+```ts
+// Create group layer with a nested sub group
+const group = new GroupLayer({
+    id: "group",
+    title: "a group layer",
+    layers: [
+        new SimpleLayer({
+            id: "member",
+            title: "group member",
+            olLayer: olLayer1
+        }),
+        new GroupLayer({
+            id: "subgroup",
+            title: "a nested group layer",
+            layers: [
+                new SimpleLayer({
+                    id: "submember",
+                    title: "subgroup member",
+                    olLayer: olLayer2
+                })
+            ]
+        })
+    ]
+});
+
+const childLayers = group.layers; // Access child layers
+```
+
+> Limitations:
+>
+> -   Do not add or remove layers directly to or from the underlying OpenLayers layer group (`group.olLayer`)! Changes are not synchronized with the `GroupLayer` instance.
+> -   Currently, it is not possible to manipulate (add or remove) the child layers of a `GroupLayer` during runtime.
+
 #### Register additional projections
 
 The map supports only the following projections by default: `EPSG:4326`, `EPSG:3857`, `EPSG:25832` and `EPSG:25833`.
@@ -693,17 +734,80 @@ In those cases, the properties or methods provided by this package should always
 
 #### Layer classes
 
-This package currently only provides two layer implementations:
+This package currently provides five layer implementations: `SimpleLayer`, `WMSLayer`, `WMTSLayer`, `GroupLayer` and `WMSSublayer`.
+
+The following diagram shows the inheritance structure of the corresponding layer types. The diagram is only intended to show the hierarchy of the layer types; for details on the properties and methods of the layer types, refer to the respective API documentation.
+
+```mermaid
+---
+config:
+  class:
+    hideEmptyMembersBox: true
+---
+classDiagram
+class AnyLayerBaseType {
+  type: string
+}
+<<abstract>> AnyLayerBaseType
+
+class LayerBaseType {
+  type: string
+}
+<<abstract>> LayerBaseType
+
+class SimpleLayer {
+  type: "simple"
+  constructor(config: SimpleLayerConfig)
+}
+
+class WMSLayer {
+  type: "wms"
+  constructor(config: WMSLayerConfig)
+}
+
+class WMTSLayer {
+  type: "wmts"
+  constructor(config: WMTSLayerConfig)
+}
+
+class GroupLayer {
+    type: "group"
+    constructor(config: GroupLayerConfig)
+}
 
--   `SimpleLayer`.
-    Instances of this class can be used to integrate arbitrary OpenLayers `Layer` instances into the map by configuring the `olLayer` constructor option.
-    Note that one can only achieve basic integration through this method: more advanced features such as automatic legends or sublayers will not be available.
+class Layer
+<<union>> Layer
 
--   `WMSLayer`.
-    Represents a WMS service embedded into the map.
-    Must be configured with the service's `url` and a set of sublayers.
+class Sublayer
+<<union>> Sublayer
 
-We expect to implement more classes in the future.
+class SublayerBaseType {
+  type: string
+}
+<<abstract>> SublayerBaseType
+
+class WMSSublayer {
+    type: "wms-sublayer"
+    constructor(config: WMSSublayerConfig)
+}
+
+AnyLayerBaseType <|-- LayerBaseType
+AnyLayerBaseType <|-- SublayerBaseType
+
+LayerBaseType <|-- SimpleLayer
+LayerBaseType <|-- WMSLayer
+LayerBaseType <|-- WMTSLayer
+LayerBaseType <|-- GroupLayer
+
+SublayerBaseType <|-- WMSSublayer
+
+SimpleLayer .. Layer
+WMSLayer .. Layer
+WMTSLayer .. Layer
+GroupLayer .. Layer
+
+WMSSublayer .. Sublayer
+```
 
 #### Using the map model and layers in services
 

package/api/MapModel.d.ts

@@ -1,17 +1,17 @@
 import type { EventSource, Resource } from "@open-pioneer/core";
 import type OlMap from "ol/Map";
+import type OlView from "ol/View";
 import type OlBaseLayer from "ol/layer/Base";
 import type { ExtentConfig } from "./MapConfig";
 import type { AnyLayer, Layer } from "./layers";
 import type { LayerRetrievalOptions } from "./shared";
 import type { Geometry } from "ol/geom";
-import { BaseFeature } from "./BaseFeature";
-import { StyleLike } from "ol/style/Style";
+import type { BaseFeature } from "./BaseFeature";
+import type { StyleLike } from "ol/style/Style";
+import type { Projection } from "ol/proj";
+import type { Coordinate } from "ol/coordinate";
 /** Events emitted by the {@link MapModel}. */
 export interface MapModelEvents {
-    "changed": void;
-    "changed:container": void;
-    "changed:initialExtent": void;
     "destroy": void;
 }
 /** Styleoptions supported when creating a new {@link Highlight}. */
@@ -70,7 +70,7 @@ export interface Highlight extends Resource {
     readonly isActive: boolean;
 }
 /**
- * Represents a Object
+ * Represents an object in the map.
  */
 export type DisplayTarget = BaseFeature | Geometry;
 /**
@@ -83,11 +83,10 @@ export interface MapModel extends EventSource<MapModelEvents> {
     readonly id: string;
     /**
      * The container in which the map is currently being rendered.
+     * This is the same as the target element of the underlying OpenLayers map.
      *
      * May be undefined if the map is not being rendered at the moment.
      * May change at runtime.
-     *
-     * The `changed:container` event is emitted when this value changes.
      */
     readonly container: HTMLElement | undefined;
     /**
@@ -95,8 +94,6 @@ export interface MapModel extends EventSource<MapModelEvents> {
      *
      * May be undefined before the map is shown.
      * This is guaranteed to be initialized if the promise returned by {@link whenDisplayed} has resolved.
-     *
-     * The `changed:initialExtent` event is emitted when this value changes.
      */
     readonly initialExtent: ExtentConfig | undefined;
     /**
@@ -110,6 +107,46 @@ export interface MapModel extends EventSource<MapModelEvents> {
      * The raw OpenLayers map.
      */
     readonly olMap: OlMap;
+    /**
+     * Returns the current view of the OpenLayers map.
+     */
+    readonly olView: OlView;
+    /**
+     * Returns the current zoom level of the map.
+     * Same as `olView.getZoom()`, but reactive.
+     */
+    readonly zoomLevel: number | undefined;
+    /**
+     * Returns the current resolution of the map.
+     * Same as `olView.getResolution()`, but reactive.
+     */
+    readonly resolution: number | undefined;
+    /**
+     * Returns the current center of the map.
+     * Same as `olView.getCenter()`, but reactive.
+     */
+    readonly center: Coordinate | undefined;
+    /**
+     * Returns the current projection of the map (reactive).
+     */
+    readonly projection: Projection;
+    /**
+     * Returns the current scale of the map.
+     *
+     * Technically, this is the _denominator_ of the current scale.
+     * In order to display it, use a format like `1:${scale}`.
+     */
+    readonly scale: number | undefined;
+    /**
+     * Changes the current scale of the map to the given value.
+     *
+     * Internally, this computes a new zoom level / resolution based on the scale
+     * and the current center.
+     * The new resolution is then applied to the current `olView`.
+     *
+     * See also {@link scale}.
+     */
+    setScale(newScale: number): void;
     /**
      * Returns a promise that resolves when the map has mounted in the DOM.
      */
@@ -137,14 +174,10 @@ export interface MapModel extends EventSource<MapModelEvents> {
      */
     removeHighlights(): void;
 }
-/** Events emitted by the {@link LayerCollection}. */
-export interface LayerCollectionEvents {
-    changed: void;
-}
 /**
  * Contains the layers known to a {@link MapModel}.
  */
-export interface LayerCollection extends EventSource<LayerCollectionEvents> {
+export interface LayerCollection {
     /**
      * Returns all configured base layers.
      */

package/api/layers/GroupLayer.d.ts

@@ -0,0 +1,50 @@
+import type { Group } from "ol/layer";
+import type { LayerRetrievalOptions } from "../shared";
+import type { ChildrenCollection, Layer, LayerBaseType, LayerConfig } from "./base";
+/**
+ * Configuration options to construct a {@link GroupLayer}.
+ */
+export interface GroupLayerConfig extends LayerConfig {
+    /**
+     * List of layers that belong to the new group layer.
+     *
+     * The group layer takes ownership of the given layers: they will be destroyed when the parent is destroyed.
+     * A layer must have a unique parent: it can only be added to the map or a single group layer.
+     */
+    layers: Layer[];
+}
+/**
+ * Represents a group of layers.
+ *
+ * A group layer contains a collection of {@link Layer} children.
+ * Groups can be nested to form a hierarchy.
+ */
+export interface GroupLayer extends LayerBaseType {
+    readonly type: "group";
+    /**
+     * Layers contained in this group.
+     */
+    readonly layers: GroupLayerCollection;
+    /**
+     * Raw OpenLayers group instance.
+     *
+     * **Warning:** Do not manipulate the collection of layers in this group directly, changes are not synchronized!
+     */
+    readonly olLayer: Group;
+    readonly sublayers: undefined;
+}
+/**
+ * Contains {@link Layer} instances that belong to a {@link GroupLayer}
+ */
+export interface GroupLayerCollection extends ChildrenCollection<Layer> {
+    /**
+     * Returns all layers in this collection
+     */
+    getLayers(options?: LayerRetrievalOptions): Layer[];
+}
+export interface GroupLayerConstructor {
+    prototype: GroupLayer;
+    /** Creates a new {@link GroupLayer}. */
+    new (config: GroupLayerConfig): GroupLayer;
+}
+export declare const GroupLayer: GroupLayerConstructor;

package/api/layers/GroupLayer.js

@@ -0,0 +1,6 @@
+import { GroupLayerImpl } from '../../model/layers/GroupLayerImpl.js';
+
+const GroupLayer = GroupLayerImpl;
+
+export { GroupLayer };
+//# sourceMappingURL=GroupLayer.js.map

package/api/layers/GroupLayer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GroupLayer.js","sources":["GroupLayer.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2023 Open Pioneer project (https://github.com/open-pioneer)\n// SPDX-License-Identifier: Apache-2.0\nimport type { Group } from \"ol/layer\";\nimport { GroupLayerImpl } from \"../../model/layers/GroupLayerImpl\";\nimport type { LayerRetrievalOptions } from \"../shared\";\nimport type { ChildrenCollection, Layer, LayerBaseType, LayerConfig } from \"./base\";\n\n/**\n * Configuration options to construct a {@link GroupLayer}.\n */\nexport interface GroupLayerConfig extends LayerConfig {\n    /**\n     * List of layers that belong to the new group layer.\n     *\n     * The group layer takes ownership of the given layers: they will be destroyed when the parent is destroyed.\n     * A layer must have a unique parent: it can only be added to the map or a single group layer.\n     */\n    layers: Layer[];\n}\n\n/**\n * Represents a group of layers.\n *\n * A group layer contains a collection of {@link Layer} children.\n * Groups can be nested to form a hierarchy.\n */\nexport interface GroupLayer extends LayerBaseType {\n    readonly type: \"group\";\n\n    /**\n     * Layers contained in this group.\n     */\n    readonly layers: GroupLayerCollection;\n\n    /**\n     * Raw OpenLayers group instance.\n     *\n     * **Warning:** Do not manipulate the collection of layers in this group directly, changes are not synchronized!\n     */\n    readonly olLayer: Group;\n\n    readonly sublayers: undefined;\n}\n\n/**\n * Contains {@link Layer} instances that belong to a {@link GroupLayer}\n */\nexport interface GroupLayerCollection extends ChildrenCollection<Layer> {\n    /**\n     * Returns all layers in this collection\n     */\n    getLayers(options?: LayerRetrievalOptions): Layer[];\n}\n\nexport interface GroupLayerConstructor {\n    prototype: GroupLayer;\n\n    /** Creates a new {@link GroupLayer}. */\n    new (config: GroupLayerConfig): GroupLayer;\n}\n\nexport const GroupLayer: GroupLayerConstructor = GroupLayerImpl;\n"],"names":[],"mappings":";;AA6DO,MAAM,UAAoC,GAAA;;;;"}

package/api/layers/SimpleLayer.d.ts

@@ -22,5 +22,6 @@ export interface SimpleLayerConstructor {
  */
 export interface SimpleLayer extends LayerBaseType {
     readonly type: "simple";
+    readonly layers: undefined;
 }
 export declare const SimpleLayer: SimpleLayerConstructor;

package/api/layers/SimpleLayer.js.map

@@ -1 +1 @@
-{"version":3,"file":"SimpleLayer.js","sources":["SimpleLayer.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2023 Open Pioneer project (https://github.com/open-pioneer)\n// SPDX-License-Identifier: Apache-2.0\nimport type OlBaseLayer from \"ol/layer/Base\";\nimport { LayerConfig, LayerBaseType } from \"./base\";\nimport { SimpleLayerImpl } from \"../../model/layers/SimpleLayerImpl\";\n\n/**\n * Options to construct a simple layer.\n *\n * Simple layers are wrappers around a custom OpenLayers layer.\n */\nexport interface SimpleLayerConfig extends LayerConfig {\n    /**\n     * The raw OpenLayers instance.\n     */\n    olLayer: OlBaseLayer;\n}\n\n/** Constructor for {@link SimpleLayer}. */\nexport interface SimpleLayerConstructor {\n    prototype: SimpleLayer;\n\n    /** Creates a new {@link SimpleLayer}. */\n    new (config: SimpleLayerConfig): SimpleLayer;\n}\n\n/**\n * A simple layer type wrapping an OpenLayers layer.\n */\nexport interface SimpleLayer extends LayerBaseType {\n    readonly type: \"simple\";\n}\n\nexport const SimpleLayer: SimpleLayerConstructor = SimpleLayerImpl;\n"],"names":[],"mappings":";;AAiCO,MAAM,WAAsC,GAAA;;;;"}
+{"version":3,"file":"SimpleLayer.js","sources":["SimpleLayer.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2023 Open Pioneer project (https://github.com/open-pioneer)\n// SPDX-License-Identifier: Apache-2.0\nimport type OlBaseLayer from \"ol/layer/Base\";\nimport { LayerConfig, LayerBaseType } from \"./base\";\nimport { SimpleLayerImpl } from \"../../model/layers/SimpleLayerImpl\";\n\n/**\n * Options to construct a simple layer.\n *\n * Simple layers are wrappers around a custom OpenLayers layer.\n */\nexport interface SimpleLayerConfig extends LayerConfig {\n    /**\n     * The raw OpenLayers instance.\n     */\n    olLayer: OlBaseLayer;\n}\n\n/** Constructor for {@link SimpleLayer}. */\nexport interface SimpleLayerConstructor {\n    prototype: SimpleLayer;\n\n    /** Creates a new {@link SimpleLayer}. */\n    new (config: SimpleLayerConfig): SimpleLayer;\n}\n\n/**\n * A simple layer type wrapping an OpenLayers layer.\n */\nexport interface SimpleLayer extends LayerBaseType {\n    readonly type: \"simple\";\n\n    readonly layers: undefined;\n}\n\nexport const SimpleLayer: SimpleLayerConstructor = SimpleLayerImpl;\n"],"names":[],"mappings":";;AAmCO,MAAM,WAAsC,GAAA;;;;"}

package/api/layers/WMSLayer.d.ts

@@ -32,6 +32,7 @@ export interface WMSSublayerConfig extends LayerBaseConfig {
 export interface WMSLayer extends LayerBaseType {
     readonly type: "wms";
     readonly sublayers: SublayersCollection<WMSSublayer>;
+    readonly layers: undefined;
     /** The URL of the WMS service that was used during layer construction. */
     readonly url: string;
 }

package/api/layers/WMSLayer.js.map

@@ -1 +1 @@
-{"version":3,"file":"WMSLayer.js","sources":["WMSLayer.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2023 Open Pioneer project (https://github.com/open-pioneer)\n// SPDX-License-Identifier: Apache-2.0\nimport type { Options as WMSSourceOptions } from \"ol/source/ImageWMS\";\nimport { WMSLayerImpl } from \"../../model/layers/WMSLayerImpl\";\nimport type {\n    LayerBaseConfig,\n    SublayersCollection,\n    LayerConfig,\n    LayerBaseType,\n    SublayerBaseType\n} from \"./base\";\n\n/**\n * Configuration options to construct a WMS layer.\n */\nexport interface WMSLayerConfig extends LayerConfig {\n    /** URL of the WMS service. */\n    url: string;\n\n    /** Configures the layer's sublayers. */\n    sublayers?: WMSSublayerConfig[];\n\n    /**\n     * Additional source options for the layer's WMS source.\n     *\n     * NOTE: These options are intended for advanced configuration:\n     * the WMS Layer manages some of the OpenLayers source options itself.\n     */\n    sourceOptions?: Partial<WMSSourceOptions>;\n}\n\n/**\n * Configuration options to construct the sublayers of a WMS layer.\n */\nexport interface WMSSublayerConfig extends LayerBaseConfig {\n    /**\n     * The name of the WMS sublayer in the service's capabilities.\n     * Not mandatory, e.g. for WMS group layer. See [WMS spec](https://www.ogc.org/standard/wms/).\n     */\n    name?: string;\n\n    /** Configuration for nested sublayers. */\n    sublayers?: WMSSublayerConfig[];\n}\n\n/** Represents a WMS layer. */\nexport interface WMSLayer extends LayerBaseType {\n    readonly type: \"wms\";\n\n    readonly sublayers: SublayersCollection<WMSSublayer>;\n\n    /** The URL of the WMS service that was used during layer construction. */\n    readonly url: string;\n}\n\n/** Represents a WMS sublayer */\nexport interface WMSSublayer extends SublayerBaseType {\n    readonly type: \"wms-sublayer\";\n    /**\n     * The name of the WMS sublayer in the service's capabilities.\n     *\n     * Is optional as a WMS group layer in a WMS service does not need to have a name.\n     */\n    readonly name: string | undefined;\n}\n\n/**\n * Constructor for {@link WMSLayer}.\n */\nexport interface WMSLayerConstructor {\n    prototype: WMSLayer;\n\n    /** Creates a new {@link WMSLayer}. */\n    new (config: WMSLayerConfig): WMSLayer;\n}\n\nexport const WMSLayer: WMSLayerConstructor = WMSLayerImpl;\n"],"names":[],"mappings":";;AA4EO,MAAM,QAAgC,GAAA;;;;"}
+{"version":3,"file":"WMSLayer.js","sources":["WMSLayer.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2023 Open Pioneer project (https://github.com/open-pioneer)\n// SPDX-License-Identifier: Apache-2.0\nimport type { Options as WMSSourceOptions } from \"ol/source/ImageWMS\";\nimport { WMSLayerImpl } from \"../../model/layers/WMSLayerImpl\";\nimport type {\n    LayerBaseConfig,\n    SublayersCollection,\n    LayerConfig,\n    LayerBaseType,\n    SublayerBaseType\n} from \"./base\";\n\n/**\n * Configuration options to construct a WMS layer.\n */\nexport interface WMSLayerConfig extends LayerConfig {\n    /** URL of the WMS service. */\n    url: string;\n\n    /** Configures the layer's sublayers. */\n    sublayers?: WMSSublayerConfig[];\n\n    /**\n     * Additional source options for the layer's WMS source.\n     *\n     * NOTE: These options are intended for advanced configuration:\n     * the WMS Layer manages some of the OpenLayers source options itself.\n     */\n    sourceOptions?: Partial<WMSSourceOptions>;\n}\n\n/**\n * Configuration options to construct the sublayers of a WMS layer.\n */\nexport interface WMSSublayerConfig extends LayerBaseConfig {\n    /**\n     * The name of the WMS sublayer in the service's capabilities.\n     * Not mandatory, e.g. for WMS group layer. See [WMS spec](https://www.ogc.org/standard/wms/).\n     */\n    name?: string;\n\n    /** Configuration for nested sublayers. */\n    sublayers?: WMSSublayerConfig[];\n}\n\n/** Represents a WMS layer. */\nexport interface WMSLayer extends LayerBaseType {\n    readonly type: \"wms\";\n\n    readonly sublayers: SublayersCollection<WMSSublayer>;\n    readonly layers: undefined;\n\n    /** The URL of the WMS service that was used during layer construction. */\n    readonly url: string;\n}\n\n/** Represents a WMS sublayer */\nexport interface WMSSublayer extends SublayerBaseType {\n    readonly type: \"wms-sublayer\";\n    /**\n     * The name of the WMS sublayer in the service's capabilities.\n     *\n     * Is optional as a WMS group layer in a WMS service does not need to have a name.\n     */\n    readonly name: string | undefined;\n}\n\n/**\n * Constructor for {@link WMSLayer}.\n */\nexport interface WMSLayerConstructor {\n    prototype: WMSLayer;\n\n    /** Creates a new {@link WMSLayer}. */\n    new (config: WMSLayerConfig): WMSLayer;\n}\n\nexport const WMSLayer: WMSLayerConstructor = WMSLayerImpl;\n"],"names":[],"mappings":";;AA6EO,MAAM,QAAgC,GAAA;;;;"}

package/api/layers/WMTSLayer.d.ts

@@ -23,6 +23,7 @@ export interface WMTSLayer extends LayerBaseType {
     readonly name: string;
     /** The name of the tile matrix set in the service's capabilities. */
     readonly matrixSet: string;
+    readonly layers: undefined;
 }
 export interface WMTSLayerConstructor {
     prototype: WMTSLayer;

package/api/layers/WMTSLayer.js.map

@@ -1 +1 @@
-{"version":3,"file":"WMTSLayer.js","sources":["WMTSLayer.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2023 Open Pioneer project (https://github.com/open-pioneer)\n// SPDX-License-Identifier: Apache-2.0\nimport type { Options as WMSSourceOptions } from \"ol/source/ImageWMS\";\nimport { LayerBaseType, LayerConfig } from \"./base\";\nimport { WMTSLayerImpl } from \"../../model/layers/WMTSLayerImpl\";\nexport interface WMTSLayerConfig extends LayerConfig {\n    /** URL of the WMTS service. */\n    url: string;\n\n    /** The name of the WMTS layer in the service's capabilities. */\n    name: string;\n\n    /** The name of the tile matrix set in the service's capabilities. */\n    matrixSet: string;\n\n    /**\n     * Additional source options for the layer's WMTS source.\n     *\n     * NOTE: These options are intended for advanced configuration:\n     * the WMTS Layer manages some of the OpenLayers source options itself.\n     */\n    sourceOptions?: Partial<WMSSourceOptions>;\n}\nexport interface WMTSLayer extends LayerBaseType {\n    readonly type: \"wmts\";\n\n    /** URL of the WMTS service. */\n    readonly url: string;\n\n    /** The name of the WMTS layer in the service's capabilities. */\n    readonly name: string;\n\n    /** The name of the tile matrix set in the service's capabilities. */\n    readonly matrixSet: string;\n}\nexport interface WMTSLayerConstructor {\n    prototype: WMTSLayer;\n\n    /** Creates a new {@link WMTSLayer}. */\n    new (config: WMTSLayerConfig): WMTSLayer;\n}\n\nexport const WMTSLayer: WMTSLayerConstructor = WMTSLayerImpl;\n"],"names":[],"mappings":";;AA0CO,MAAM,SAAkC,GAAA;;;;"}
+{"version":3,"file":"WMTSLayer.js","sources":["WMTSLayer.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2023 Open Pioneer project (https://github.com/open-pioneer)\n// SPDX-License-Identifier: Apache-2.0\nimport type { Options as WMSSourceOptions } from \"ol/source/ImageWMS\";\nimport { LayerBaseType, LayerConfig } from \"./base\";\nimport { WMTSLayerImpl } from \"../../model/layers/WMTSLayerImpl\";\n\nexport interface WMTSLayerConfig extends LayerConfig {\n    /** URL of the WMTS service. */\n    url: string;\n\n    /** The name of the WMTS layer in the service's capabilities. */\n    name: string;\n\n    /** The name of the tile matrix set in the service's capabilities. */\n    matrixSet: string;\n\n    /**\n     * Additional source options for the layer's WMTS source.\n     *\n     * NOTE: These options are intended for advanced configuration:\n     * the WMTS Layer manages some of the OpenLayers source options itself.\n     */\n    sourceOptions?: Partial<WMSSourceOptions>;\n}\n\nexport interface WMTSLayer extends LayerBaseType {\n    readonly type: \"wmts\";\n\n    /** URL of the WMTS service. */\n    readonly url: string;\n\n    /** The name of the WMTS layer in the service's capabilities. */\n    readonly name: string;\n\n    /** The name of the tile matrix set in the service's capabilities. */\n    readonly matrixSet: string;\n\n    readonly layers: undefined;\n}\n\nexport interface WMTSLayerConstructor {\n    prototype: WMTSLayer;\n\n    /** Creates a new {@link WMTSLayer}. */\n    new (config: WMTSLayerConfig): WMTSLayer;\n}\n\nexport const WMTSLayer: WMTSLayerConstructor = WMTSLayerImpl;\n"],"names":[],"mappings":";;AA+CO,MAAM,SAAkC,GAAA;;;;"}

package/api/layers/base.d.ts

@@ -4,16 +4,10 @@ import type { MapModel } from "../MapModel";
 import type { LayerRetrievalOptions } from "../shared";
 import type { SimpleLayer } from "./SimpleLayer";
 import type { WMSLayer, WMSSublayer } from "./WMSLayer";
-import { WMTSLayer } from "./WMTSLayer";
+import type { WMTSLayer } from "./WMTSLayer";
+import type { GroupLayer, GroupLayerCollection } from "./GroupLayer";
 /** Events emitted by the {@link Layer} and other layer types. */
 export interface LayerBaseEvents {
-    "changed": void;
-    "changed:title": void;
-    "changed:legend": void;
-    "changed:description": void;
-    "changed:visible": void;
-    "changed:attributes": void;
-    "changed:loadState": void;
     "destroy": void;
 }
 /** The load state of a layer. */
@@ -62,6 +56,12 @@ export interface AnyLayerBaseType<AdditionalEvents = {}> extends EventSource<Lay
     readonly type: AnyLayerTypes;
     /** The map this layer belongs to. */
     readonly map: MapModel;
+    /**
+     * The direct parent of this layer instance, used for sublayers or for layers in a group layer.
+     *
+     * The property shall be undefined if the layer is not a sublayer or member of a group layer.
+     */
+    readonly parent: AnyLayer | undefined;
     /**
      * The unique id of this layer within its map model.
      *
@@ -85,9 +85,27 @@ export interface AnyLayerBaseType<AdditionalEvents = {}> extends EventSource<Lay
      */
     readonly legend: string | undefined;
     /**
-     * The collection of child sublayers for this layer.
+     * The direct children of this layer.
+     *
+     * The children may either be a set of operational layers (e.g. for a group layer) or a set of sublayers, or `undefined`.
+     *
+     * See also {@link layers} and {@link sublayers}.
+     */
+    readonly children: ChildrenCollection<AnyLayer> | undefined;
+    /**
+     * If this layer is a group layer this property contains a collection of all layers that a members to the group.
+     *
+     * The property shall be `undefined` if it is not a group layer.
+     *
+     * The properties `layers` and `sublayers` are mutually exclusive.
+     */
+    readonly layers: GroupLayerCollection | undefined;
+    /**
+     * The collection of child sublayers for this layer. Sublayers are layers that cannot exist without an appropriate parent layer.
      *
      * Layers that can never have any sublayers may not have a `sublayers` collection.
+     *
+     * The properties `layers` and `sublayers` are mutually exclusive.
      */
     readonly sublayers: SublayersCollection | undefined;
     /**
@@ -182,15 +200,18 @@ export interface SublayerBaseType extends AnyLayerBaseType {
     readonly parentLayer: Layer;
 }
 /**
- * Events emitted by the {@link SublayersCollection}.
+ * Contains the children of a layer.
  */
-export interface SublayersCollectionEvents {
-    changed: void;
+export interface ChildrenCollection<LayerType> {
+    /**
+     * Returns the items in this collection.
+     */
+    getItems(options?: LayerRetrievalOptions): LayerType[];
 }
 /**
  * Contains the sublayers that belong to a {@link Layer} or {@link Sublayer}.
  */
-export interface SublayersCollection<SublayerType = Sublayer> extends EventSource<SublayersCollectionEvents> {
+export interface SublayersCollection<SublayerType = Sublayer> extends ChildrenCollection<SublayerType> {
     /**
      * Returns the child sublayers in this collection.
      */
@@ -199,7 +220,7 @@ export interface SublayersCollection<SublayerType = Sublayer> extends EventSourc
 /**
  * Union type for all layers (extending {@link LayerBaseType})
  */
-export type Layer = SimpleLayer | WMSLayer | WMTSLayer;
+export type Layer = SimpleLayer | WMSLayer | WMTSLayer | GroupLayer;
 export type LayerTypes = Layer["type"];
 /**
  * Union type for all sublayers (extending {@link SublayerBaseType}