@open-pioneer/map 0.11.0 → 0.12.0-dev.20250905090001

package/CHANGELOG.md

@@ -1,12 +1,112 @@
 # @open-pioneer/map
 
+## 0.12.0-dev.20250905090001
+
+### Minor Changes
+
+- 2702df4: Introduce `internal` property for all layer types (including sublayers). If `internal` is `true` (default: `false`) the layer is not considered by any UI widget (e.g. legend and Toc). The `internal` state of a layer is not to be confused with the layer's visibility on the map which is determined by the `visible` property.
+
+    ```typescript
+    //internal layer is visible on the map but hidden in UI elements like legend and Toc
+    const internalLayer = new SimpleLayer({
+        id: "layer1",
+        title: "layer 1",
+        olLayer: myOlLayer,
+        visible: true,
+        internal: true
+    });
+    ```
+
+- 5df900f: Add a new hook `useMapModelValue(props?)`.
+  The hook returns either the directly configured `map` (via props) or the default map from a parent `DefaultMapProvider`.
+  If neither is present, an error will be thrown.
+
+    This hook is used in all components that work with the map.
+    The typical usage works like this:
+
+    ```ts
+    import { MapModelProps, useMapModelValue } from "@open-pioneer/map";
+
+    // optional `map` property inherited from `MapModelProps`
+    export interface MyComponentProps extends MapModelProps {
+        // ... other properties
+    }
+
+    export function MyComponent(props) {
+        const map = useMapModelValue(props); // looks up the map
+    }
+    ```
+
+    You can also call this hook without any arguments:
+
+    ```ts
+    // Map model from DefaultMapProvider or an error.
+    const mapModel = useMapModelValue();
+    ```
+
+    This hook should replace _most_ usages `useMapModel`, which can't return the map model directly since it may not have finished construction yet.
+
+- aeb9000: Add new `"topmost"` option to add layers that are always displayed on the top (above all other layers).
+
+    A new layers can be added at `topmost` to ensure that this layer will always be displayed on top of the other layers.
+    This can be used, for example, to implement highlights or to draw graphics.
+    Layers added at `"topmost"` will always be shown above layers at `"top"`.
+
+    When using the `"above"` or `"below"` options with a `"topmost"` reference layer, that layer becomes `"topmost"` as well.
+
+    ```typescript
+    import { MapModel, SimpleLayer } from "@open-pioneer/map";
+
+    const highlightLayer = new SimpleLayer({
+        title: "highlights",
+        olLayer: myOlLayer
+    });
+    //always displayed at the top
+    myMapModel.layers.addLayer(highlightLayer, { at: "topmost" });
+    ```
+
+- 5df900f: Deprecate the parameter-less signature of `useMapModel()`:
+
+    ```ts
+    // Returns the DefaultMapProvider's map, but wrapped in a result value (loading/resolved/rejected)
+    const result = useMapModel();
+    ```
+
+    Use `useMapModelValue()` instead:
+
+    ```ts
+    // Returns the map model directly.
+    const mapModel = useMapModelValue();
+    ```
+
+    All other signatures of `useMapModel()` are still fully supported.
+
+### Patch Changes
+
+- 29a10df: Support buffer for zoom geometries.
+
+    For example:
+
+    ```ts
+    const map: MapModel = ...;
+    const highlight = map.highlightAndZoom(someGeometries, {
+        // Grows extent by 10%
+        buffer: 0.1
+    });
+    ```
+
+- 10d2fe7: Update dependencies
+- 12561fe: The default value of the `role` prop on the `MapContainer` was changed to `application` to allow map keyboard navigation while using NVDA screen reader.
+- 8986b3b: Remove obsolete dependency @types/proj4
+- f1f69f2: Update to OpenLayers 10.6.1
+- da6a410: Update dependencies
+
 ## 0.11.0
 
 ### Minor Changes
 
 - 66179bc: Update to core-packages v4.0.0
 - acd5115: **Breaking:** Remove the following hooks, which were deprecated since version 0.8.0:
-
     - useView
     - useProjection
     - useResolution
@@ -259,7 +359,6 @@
     `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`
@@ -277,7 +376,6 @@
     ```
 
 - 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.
@@ -327,7 +425,6 @@
     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()`)
@@ -359,7 +456,6 @@
     Two type guards have been implemented that allow to check if a layer instance is a `Layer` or `Sublayer`: `isLayer()`and `isSublayer()` (see example below).
 
     The following `type` attribute values have been implemented at the layers:
-
     - SimpleLayer: `simple`
     - WMSLayer: `wms`
     - WMSSubLayer: `wms-sublayer`

package/MapRegistryImpl.js.map

@@ -1 +1 @@
-{"version":3,"file":"MapRegistryImpl.js","sources":["MapRegistryImpl.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2023-2025 Open Pioneer project (https://github.com/open-pioneer)\n// SPDX-License-Identifier: Apache-2.0\nimport { createLogger } from \"@open-pioneer/core\";\nimport { HttpService } from \"@open-pioneer/http\";\nimport { PackageIntl, Service, ServiceOptions } from \"@open-pioneer/runtime\";\nimport OlMap from \"ol/Map\";\nimport { MapConfigProvider, MapModel, MapRegistry } from \"./api\";\nimport { createMapModel } from \"./model/createMapModel\";\nimport { MapModelImpl } from \"./model/MapModelImpl\";\n\nconst LOG = createLogger(\"map:MapRegistry\");\n\ninterface References {\n    providers: MapConfigProvider[];\n    httpService: HttpService;\n}\n\ntype ModelJobResult = { kind: \"model\"; model: MapModelImpl } | { kind: \"error\"; error: Error };\n\nexport class MapRegistryImpl implements Service, MapRegistry {\n    #intl: PackageIntl;\n    #httpService: HttpService;\n\n    #configProviders = new Map<string, MapConfigProvider>();\n    #entries = new Map<string, ModelJobResult>();\n    #modelCreationJobs = new Map<string, Promise<ModelJobResult>>();\n    #modelsByOlMap = new WeakMap<OlMap, MapModel>();\n    #destroyed = false;\n\n    constructor({ references, intl }: ServiceOptions<References>) {\n        this.#intl = intl;\n        this.#httpService = references.httpService;\n\n        const providers = references.providers;\n        for (const provider of providers) {\n            this.#configProviders.set(provider.mapId, provider);\n        }\n    }\n\n    destroy(): void {\n        if (this.#destroyed) {\n            return;\n        }\n\n        LOG.info(`Destroy map registry and all maps`);\n        this.#destroyed = true;\n        this.#entries.forEach((model) => {\n            model.kind === \"model\" && model.model.destroy();\n        });\n        this.#entries.clear();\n        this.#modelCreationJobs.clear();\n    }\n\n    async getMapModel(mapId: string): Promise<MapModel | undefined> {\n        if (this.#destroyed) {\n            throw new Error(\"MapRegistry has already been destroyed.\");\n        }\n\n        const creationJob = this.#modelCreationJobs.get(mapId);\n        if (creationJob) {\n            return unbox(await creationJob);\n        }\n\n        const entry = this.#entries.get(mapId);\n        if (entry) {\n            return unbox(entry);\n        }\n\n        const provider = this.#configProviders.get(mapId);\n        if (!provider) {\n            LOG.debug(`Failed to find a config provider for map id '${mapId}'.`);\n            return undefined;\n        }\n\n        const modelPromise = this.#createModel(mapId, provider).catch((cause) => {\n            const error = new Error(`Failed to construct map '${mapId}'`, { cause });\n            const entry: ModelJobResult = { kind: \"error\", error };\n            this.#modelCreationJobs.delete(mapId);\n            this.#entries.set(mapId, entry);\n            return entry;\n        });\n        this.#modelCreationJobs.set(mapId, modelPromise);\n        return unbox(await modelPromise);\n    }\n\n    async expectMapModel(mapId: string): Promise<MapModel> {\n        const model = await this.getMapModel(mapId);\n        if (!model) {\n            throw new Error(`No configuration available for map with id '${mapId}'.`);\n        }\n        return model;\n    }\n\n    getMapModelByRawInstance(olMap: OlMap): MapModel | undefined {\n        return this.#modelsByOlMap.get(olMap);\n    }\n\n    async #createModel(mapId: string, provider: MapConfigProvider): Promise<ModelJobResult> {\n        LOG.info(`Creating map with id '${mapId}'`);\n        const mapConfig = await provider.getMapConfig();\n        const mapModel = await createMapModel(mapId, mapConfig, this.#intl, this.#httpService);\n\n        if (this.#destroyed) {\n            mapModel.destroy();\n            throw new Error(`MapRegistry has been destroyed.`);\n        }\n\n        const entry: ModelJobResult = { kind: \"model\", model: mapModel };\n        this.#entries.set(mapId, entry);\n        this.#modelCreationJobs.delete(mapId);\n        this.#modelsByOlMap.set(mapModel.olMap, mapModel);\n        return entry;\n    }\n}\n\nfunction unbox(entry: ModelJobResult): MapModelImpl {\n    if (entry.kind === \"error\") {\n        throw entry.error;\n    }\n    return entry.model;\n}\n"],"names":["entry"],"mappings":"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"}
+{"version":3,"file":"MapRegistryImpl.js","sources":["MapRegistryImpl.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2023-2025 Open Pioneer project (https://github.com/open-pioneer)\n// SPDX-License-Identifier: Apache-2.0\nimport { createLogger } from \"@open-pioneer/core\";\nimport { HttpService } from \"@open-pioneer/http\";\nimport { PackageIntl, Service, ServiceOptions } from \"@open-pioneer/runtime\";\nimport OlMap from \"ol/Map\";\nimport { MapConfigProvider, MapModel, MapRegistry } from \"./api\";\nimport { createMapModel } from \"./model/createMapModel\";\nimport { MapModelImpl } from \"./model/MapModelImpl\";\n\nconst LOG = createLogger(\"map:MapRegistry\");\n\ninterface References {\n    providers: MapConfigProvider[];\n    httpService: HttpService;\n}\n\ntype ModelJobResult = { kind: \"model\"; model: MapModelImpl } | { kind: \"error\"; error: Error };\n\nexport class MapRegistryImpl implements Service, MapRegistry {\n    #intl: PackageIntl;\n    #httpService: HttpService;\n\n    #configProviders = new Map<string, MapConfigProvider>();\n    #entries = new Map<string, ModelJobResult>();\n    #modelCreationJobs = new Map<string, Promise<ModelJobResult>>();\n    #modelsByOlMap = new WeakMap<OlMap, MapModel>();\n    #destroyed = false;\n\n    constructor({ references, intl }: ServiceOptions<References>) {\n        this.#intl = intl;\n        this.#httpService = references.httpService;\n\n        const providers = references.providers;\n        for (const provider of providers) {\n            this.#configProviders.set(provider.mapId, provider);\n        }\n    }\n\n    destroy(): void {\n        if (this.#destroyed) {\n            return;\n        }\n\n        LOG.info(`Destroy map registry and all maps`);\n        this.#destroyed = true;\n        this.#entries.forEach((model) => {\n            model.kind === \"model\" && model.model.destroy();\n        });\n        this.#entries.clear();\n        this.#modelCreationJobs.clear();\n    }\n\n    async getMapModel(mapId: string): Promise<MapModel | undefined> {\n        if (this.#destroyed) {\n            throw new Error(\"MapRegistry has already been destroyed.\");\n        }\n\n        const creationJob = this.#modelCreationJobs.get(mapId);\n        if (creationJob) {\n            return unbox(await creationJob);\n        }\n\n        const entry = this.#entries.get(mapId);\n        if (entry) {\n            return unbox(entry);\n        }\n\n        const provider = this.#configProviders.get(mapId);\n        if (!provider) {\n            LOG.debug(`Failed to find a config provider for map id '${mapId}'.`);\n            return undefined;\n        }\n\n        const modelPromise = this.#createModel(mapId, provider).catch((cause) => {\n            const error = new Error(`Failed to construct map '${mapId}'`, { cause });\n            const entry: ModelJobResult = { kind: \"error\", error };\n            this.#modelCreationJobs.delete(mapId);\n            this.#entries.set(mapId, entry);\n            return entry;\n        });\n        this.#modelCreationJobs.set(mapId, modelPromise);\n        return unbox(await modelPromise);\n    }\n\n    async expectMapModel(mapId: string): Promise<MapModel> {\n        const model = await this.getMapModel(mapId);\n        if (!model) {\n            throw new Error(`No configuration available for map with id '${mapId}'.`);\n        }\n        return model;\n    }\n\n    getMapModelByRawInstance(olMap: OlMap): MapModel | undefined {\n        return this.#modelsByOlMap.get(olMap);\n    }\n\n    async #createModel(mapId: string, provider: MapConfigProvider): Promise<ModelJobResult> {\n        LOG.info(`Creating map with id '${mapId}'`);\n        const mapConfig = await provider.getMapConfig();\n        const mapModel = await createMapModel(mapId, mapConfig, this.#intl, this.#httpService);\n\n        if (this.#destroyed) {\n            mapModel.destroy();\n            throw new Error(`MapRegistry has been destroyed.`);\n        }\n\n        const entry: ModelJobResult = { kind: \"model\", model: mapModel };\n        this.#entries.set(mapId, entry);\n        this.#modelCreationJobs.delete(mapId);\n        this.#modelsByOlMap.set(mapModel.olMap, mapModel);\n        return entry;\n    }\n}\n\nfunction unbox(entry: ModelJobResult): MapModelImpl {\n    if (entry.kind === \"error\") {\n        throw entry.error;\n    }\n    return entry.model;\n}\n"],"names":["entry"],"mappings":"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"}

package/README.md

@@ -280,9 +280,9 @@ Based on the example above, you can set different properties using the layer API
 Example: How to set different properties.
 
 ```js
-import { useMapModel } from "@open-pioneer/map";
+import { useMapModelValue } from "@open-pioneer/map";
 
-const { map } = useMapModel(mapId);
+const map = useMapModelValue();
 const layer = map.layers.getLayerById("abe0e3f8-0ba2-409c-b6b4-9d8429c732e3");
 
 layer.setDescription("new description");
@@ -726,7 +726,7 @@ The most important API items are as follows:
 - The `MapRegistry` service (inject via `"map.MapRegistry"`).
   This service is used to obtain a reference to the `MapModel` via `registry.getMapModel(mapId)`.
 
-    > NOTE: From inside a React component you can also use the hook `useMapModel(mapId)` (or `useMapModel()` if using the DefaultMapProvider).
+    > NOTE: From inside a React component you can also use the hook `useMapModel(mapId)` (or `useMapModelValue()` if using the DefaultMapProvider).
 
 - The `MapModel` represents a map in an application.
   Through the `MapModel` one can obtain the map's base layers, operational layers and so on.
@@ -869,27 +869,39 @@ export class TestService {
 
 #### Using the map model in React components
 
-To access the map model instance, use the React hook `useMapModel`.
+To access the map model instance, use the React hooks `useMapModel` or `useMapModelValue`.
 
-Example: Center map to given coordinates using the map model.
+- `useMapModelValue` returns the map model specified by a `DefaultMapProvider` parent.
+  This is a convenient API to avoid passing the map model as a prop everywhere:
 
-```js
-import { useMapModel } from "@open-pioneer/map";
-import { MAP_ID } from "./MapConfigProviderImpl";
+    ```tsx
+    function YourComponent() {
+        const map = useMapModelValue(); // requires a <DefaultMapProvider /> parent somewhere in the React tree
+    }
+    ```
 
-export function AppUI() {
-    // mapState.map may be undefined initially, if the map is still configuring.
-    // the object may may also be in an "error" state.
-    const mapState = useMapModel(MAP_ID);
+- `useMapModel` takes a `mapId` and returns a result.
+  The result will ultimately resolve to either a map model or an error (if initialization of the map failed).
 
-    const centerBerlin = () => {
-        const olMap = mapState.map?.olMap;
-        if (olMap) {
-            olMap?.getView().fit([1489200, 6894026, 1489200, 6894026], { maxZoom: 13 });
-        }
-    };
-}
-```
+    Example: Center map to given coordinates using the map model.
+
+    ```js
+    import { useMapModel } from "@open-pioneer/map";
+    import { MAP_ID } from "./MapConfigProviderImpl";
+
+    export function AppUI() {
+        // mapState.map may be undefined initially, if the map is still configuring.
+        // the object may may also be in an "error" state.
+        const mapState = useMapModel(MAP_ID);
+
+        const centerBerlin = () => {
+            const olMap = mapState.map?.olMap;
+            if (olMap) {
+                olMap?.getView().fit([1489200, 6894026, 1489200, 6894026], { maxZoom: 13 });
+            }
+        };
+    }
+    ```
 
 ## License
 

package/api/MapModel.d.ts

@@ -35,6 +35,11 @@ export interface ZoomOptions {
      * The view padding to make all features visible.
      */
     viewPadding?: MapPadding;
+    /**
+     * The buffer factor around the extent of the zoomed features. E.g. a value of 0.1 will add 10%
+     * of the extent's width and height to the extent.
+     */
+    buffer?: number;
 }
 /** Options supported by the map model's {@link MapModel.highlightAndZoom | zoom | highlightAndZoom} method. */
 export interface HighlightZoomOptions extends HighlightOptions, ZoomOptions {

package/api/index.d.ts

@@ -7,7 +7,7 @@ export * from "./shared";
 export { getProjection, registerProjections, type ProjectionDefinition } from "../projections";
 export { MapAnchor, type MapAnchorProps, type MapAnchorPosition } from "../ui/MapAnchor";
 export { MapContainer, type MapContainerProps } from "../ui/MapContainer";
-export { useMapModel, type UseMapModelResult, type UseMapModelLoading, type UseMapModelResolved, type UseMapModelRejected, type MapModelProps } from "../ui/useMapModel";
+export { useMapModel, useMapModelValue, type UseMapModelResult, type UseMapModelLoading, type UseMapModelResolved, type UseMapModelRejected, type MapModelProps } from "../ui/useMapModel";
 export { DefaultMapProvider } from "../ui/DefaultMapProvider";
 export { calculateBufferedExtent } from "../util/geometry-utils";
 export { TOPMOST_LAYER_Z } from "../model/LayerCollectionImpl";

package/api/layers/GroupLayer.js.map

@@ -1 +1 @@
-{"version":3,"file":"GroupLayer.js","sources":["GroupLayer.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2023-2025 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, RecursiveRetrievalOptions } from \"../shared\";\nimport type { AnyLayer, 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    /**\n     * Returns a list of all layers in the collection, including all children (recursively).\n     *\n     * > Note: This includes base layers by default (see `options.filter`).\n     * > Use the `\"base\"` or `\"operational\"` short hand values to filter by base layer or operational layers.\n     * >\n     * > If the group contains many, deeply nested sub groups, this function could potentially be expensive.\n     */\n    getRecursiveLayers(options?: RecursiveRetrievalOptions): AnyLayer[];\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":";;AAuEO,MAAM,UAAoC,GAAA;;;;"}
+{"version":3,"file":"GroupLayer.js","sources":["GroupLayer.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2023-2025 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, RecursiveRetrievalOptions } from \"../shared\";\nimport type { AnyLayer, 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    /**\n     * Returns a list of all layers in the collection, including all children (recursively).\n     *\n     * > Note: This includes base layers by default (see `options.filter`).\n     * > Use the `\"base\"` or `\"operational\"` short hand values to filter by base layer or operational layers.\n     * >\n     * > If the group contains many, deeply nested sub groups, this function could potentially be expensive.\n     */\n    getRecursiveLayers(options?: RecursiveRetrievalOptions): AnyLayer[];\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":";;AAuEO,MAAM,UAAA,GAAoC;;;;"}

package/api/layers/SimpleLayer.js.map

@@ -1 +1 @@
-{"version":3,"file":"SimpleLayer.js","sources":["SimpleLayer.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2023-2025 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;;;;"}
+{"version":3,"file":"SimpleLayer.js","sources":["SimpleLayer.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2023-2025 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,WAAA,GAAsC;;;;"}

package/api/layers/WMSLayer.js.map

@@ -1 +1 @@
-{"version":3,"file":"WMSLayer.js","sources":["WMSLayer.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2023-2025 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     * Whether to automatically fetch capabilities from the service when needed (default: `true`).\n     *\n     * Setting this to `false` can be useful as a performance optimization when capabilities are not really required by the application.\n     * Note that this will disable some features of the WMS layer: for example, the legend URL will not be available.\n     */\n    fetchCapabilities?: boolean;\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":";;AAqFO,MAAM,QAAgC,GAAA;;;;"}
+{"version":3,"file":"WMSLayer.js","sources":["WMSLayer.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2023-2025 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     * Whether to automatically fetch capabilities from the service when needed (default: `true`).\n     *\n     * Setting this to `false` can be useful as a performance optimization when capabilities are not really required by the application.\n     * Note that this will disable some features of the WMS layer: for example, the legend URL will not be available.\n     */\n    fetchCapabilities?: boolean;\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":";;AAqFO,MAAM,QAAA,GAAgC;;;;"}

package/api/layers/WMTSLayer.js.map

@@ -1 +1 @@
-{"version":3,"file":"WMTSLayer.js","sources":["WMTSLayer.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2023-2025 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;;;;"}
+{"version":3,"file":"WMTSLayer.js","sources":["WMTSLayer.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2023-2025 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,SAAA,GAAkC;;;;"}

package/api/layers/base.d.ts

@@ -42,6 +42,11 @@ export interface LayerBaseConfig {
      * These can be arbitrary values.
      */
     attributes?: Record<string | symbol, unknown>;
+    /**
+     * Layers marked as internal are not considered by any UI widget (e.g. Toc or Legend)
+     * Defaults to `false`
+     */
+    internal?: boolean;
 }
 /**
  * Interface shared by all layer types (operational layers and sublayers).
@@ -110,6 +115,13 @@ export interface AnyLayerBaseType<AdditionalEvents = {}> extends EventSource<Lay
      * The properties `layers` and `sublayers` are mutually exclusive.
      */
     readonly sublayers: SublayersCollection | undefined;
+    /**
+     * Property that specifies if the layer is an "internal" layer. Internal layers are not considered by any UI widget (e.g. Toc or Legend).
+     * The internal state is independent of the layer's visibility which is determined by {@link visible}
+     *
+     * NOTE: Some UI widgets might use component specific attributes or props that have precedence over the internal property.
+     */
+    readonly internal: boolean;
     /**
      * Additional attributes associated with this layer.
      */
@@ -129,6 +141,11 @@ export interface AnyLayerBaseType<AdditionalEvents = {}> extends EventSource<Lay
      * Call {@link LayerCollection.activateBaseLayer} instead.
      */
     setVisible(newVisibility: boolean): void;
+    /**
+     * Updates the internal property of this layer to the new value.
+     * @param newIsInternal
+     */
+    setInternal(newIsInternal: boolean): void;
     /**
      * Updates the attributes of this layer.
      * Values in `newAttributes` are merged into the existing ones (i.e. via `Object.assign`).

package/api/layers/base.js.map

@@ -1 +1 @@
-{"version":3,"file":"base.js","sources":["base.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2023-2025 Open Pioneer project (https://github.com/open-pioneer)\n// SPDX-License-Identifier: Apache-2.0\nimport type { EventSource } from \"@open-pioneer/core\";\nimport type OlBaseLayer from \"ol/layer/Base\";\nimport type { MapModel } from \"../MapModel\";\nimport type { LayerRetrievalOptions, RecursiveRetrievalOptions } from \"../shared\";\nimport type { GroupLayer, GroupLayerCollection } from \"./GroupLayer\";\nimport type { SimpleLayer } from \"./SimpleLayer\";\nimport type { WMSLayer, WMSSublayer } from \"./WMSLayer\";\nimport type { WMTSLayer } from \"./WMTSLayer\";\n\n/** Events emitted by the {@link Layer} and other layer types. */\nexport interface LayerBaseEvents {\n    \"destroy\": void;\n}\n\n/** The load state of a layer. */\nexport type LayerLoadState = \"not-loaded\" | \"loading\" | \"loaded\" | \"error\";\n\n/** Custom function to check the state of a layer and returning a \"loaded\" or \"error\". */\nexport type HealthCheckFunction = (layer: Layer) => Promise<\"loaded\" | \"error\">;\n\n/**\n * Configuration options supported by all layer types (layers and sublayers).\n */\nexport interface LayerBaseConfig {\n    /**\n     * The unique id of this layer.\n     * Defaults to a generated id.\n     */\n    id?: string;\n\n    /**\n     * The human-readable title of this layer.\n     */\n    title: string;\n\n    /**\n     * The human-readable description of this layer.\n     * Defaults to an empty string.\n     */\n    description?: string;\n\n    /**\n     * Whether this layer should initially be visible.\n     * Defaults to `true`.\n     */\n    visible?: boolean;\n\n    /**\n     * Additional attributes for this layer.\n     * These can be arbitrary values.\n     */\n    attributes?: Record<string | symbol, unknown>;\n}\n\n/**\n * Interface shared by all layer types (operational layers and sublayers).\n *\n * Instances of this interface cannot be constructed directly; use a real layer\n * class such as {@link SimpleLayer} instead.\n */\nexport interface AnyLayerBaseType<AdditionalEvents = {}>\n    extends EventSource<LayerBaseEvents & AdditionalEvents> {\n    /**\n     * Identifies the type of this layer.\n     */\n    readonly type: AnyLayerTypes;\n\n    /** The map this layer belongs to. */\n    readonly map: MapModel;\n\n    /**\n     * The direct parent of this layer instance, used for sublayers or for layers in a group layer.\n     *\n     * The property shall be undefined if the layer is not a sublayer or member of a group layer.\n     */\n    readonly parent: AnyLayer | undefined;\n\n    /**\n     * The unique id of this layer within its map model.\n     *\n     * NOTE: layer ids may not be globally unique: layers that belong\n     * to different map models may have the same id.\n     */\n    readonly id: string;\n\n    /** The human-readable title of this layer. */\n    readonly title: string;\n\n    /** The human-readable description of this layer. May be empty. */\n    readonly description: string;\n\n    /**\n     * Whether the layer is visible or not.\n     *\n     * NOTE: The model's visible state may do more than influence the raw OpenLayers's visibility property.\n     * Future versions may completely remove invisible layers from the OpenLayer's map under some circumstances.\n     */\n    readonly visible: boolean;\n\n    /**\n     * Legend URL from the service capabilities, if available.\n     *\n     * Note: this property may be expanded upon in the future, e.g. to support more variants than just image URLs.\n     */\n    readonly legend: string | undefined;\n\n    /**\n     * The direct children of this layer.\n     *\n     * The children may either be a set of operational layers (e.g. for a group layer) or a set of sublayers, or `undefined`.\n     *\n     * See also {@link layers} and {@link sublayers}.\n     */\n    readonly children: ChildrenCollection<AnyLayer> | undefined;\n\n    /**\n     * If this layer is a group layer this property contains a collection of all layers that a members to the group.\n     *\n     * The property shall be `undefined` if it is not a group layer.\n     *\n     * The properties `layers` and `sublayers` are mutually exclusive.\n     */\n    readonly layers: GroupLayerCollection | undefined;\n\n    /**\n     * The collection of child sublayers for this layer. Sublayers are layers that cannot exist without an appropriate parent layer.\n     *\n     * Layers that can never have any sublayers may not have a `sublayers` collection.\n     *\n     * The properties `layers` and `sublayers` are mutually exclusive.\n     */\n    readonly sublayers: SublayersCollection | undefined;\n\n    /**\n     * Additional attributes associated with this layer.\n     */\n    readonly attributes: Readonly<Record<string | symbol, unknown>>;\n\n    /**\n     * Updates the title of this layer.\n     */\n    setTitle(newTitle: string): void;\n\n    /**\n     * Updates the description of this layer.\n     */\n    setDescription(newDescription: string): void;\n\n    /**\n     * Updates the visibility of this layer to the new value.\n     *\n     * NOTE: The visibility of base layers cannot be changed through this method.\n     * Call {@link LayerCollection.activateBaseLayer} instead.\n     */\n    setVisible(newVisibility: boolean): void;\n\n    /**\n     * Updates the attributes of this layer.\n     * Values in `newAttributes` are merged into the existing ones (i.e. via `Object.assign`).\n     */\n    updateAttributes(newAttributes: Record<string | symbol, unknown>): void;\n\n    /**\n     * Deletes the attribute of this layer.\n     */\n    deleteAttribute(deleteAttribute: string | symbol): void;\n}\n\n/**\n * Configuration options supported by all operational layer types.\n */\nexport interface LayerConfig extends LayerBaseConfig {\n    /**\n     * Whether this layer is a base layer or not.\n     * Only one base layer can be active at a time.\n     *\n     * Defaults to `false`.\n     */\n    isBaseLayer?: boolean;\n\n    /**\n     * Optional property to check the availability of the layer.\n     * It is possible to provide either a URL which indicates the state of the service (2xx response meaning \"ok\")\n     * or a {@link HealthCheckFunction} performing a custom check and returning the state.\n     */\n    healthCheck?: string | HealthCheckFunction;\n}\n\n/**\n * Represents an operational layer in the map.\n *\n * Instances of this interface cannot be constructed directly; use a real layer\n * class such as {@link SimpleLayer} instead.\n */\nexport interface LayerBaseType<AdditionalEvents = {}> extends AnyLayerBaseType<AdditionalEvents> {\n    /**\n     * Identifies the type of this layer.\n     */\n    readonly type: LayerTypes;\n\n    /**\n     * The load state of a layer.\n     */\n    readonly loadState: LayerLoadState;\n\n    /**\n     * The raw OpenLayers layer.\n     */\n    readonly olLayer: OlBaseLayer;\n\n    /**\n     * True if this layer is a base layer.\n     *\n     * Only one base layer can be visible at a time.\n     */\n    readonly isBaseLayer: boolean;\n}\n\n/**\n * Represents a sublayer of another layer.\n */\nexport interface SublayerBaseType extends AnyLayerBaseType {\n    /**\n     * Identifies the type of this sublayer.\n     */\n    readonly type: SublayerTypes;\n\n    /**\n     * The direct parent of this layer instance.\n     * This can either be the parent layer or another sublayer.\n     */\n    readonly parent: AnyLayer;\n\n    /**\n     * The parent layer that owns this sublayer.\n     */\n    readonly parentLayer: Layer;\n}\n\n/**\n * Contains the children of a layer.\n */\nexport interface ChildrenCollection<LayerType> {\n    /**\n     * Returns the items in this collection.\n     */\n    getItems(options?: LayerRetrievalOptions): LayerType[];\n}\n\n/**\n * Contains the sublayers that belong to a {@link Layer} or {@link Sublayer}.\n */\nexport interface SublayersCollection<SublayerType = Sublayer>\n    extends ChildrenCollection<SublayerType> {\n    /**\n     * Returns the child sublayers in this collection.\n     */\n    getSublayers(options?: LayerRetrievalOptions): SublayerType[];\n\n    /**\n     * Returns a list of all layers in the collection, including all children (recursively).\n     *\n     * > Note: This includes base layers by default (see `options.filter`).\n     * > Use the `\"base\"` or `\"operational\"` short hand values to filter by base layer or operational layers.\n     * >\n     * > If the collection contains many, deeply nested sublayers, this function could potentially be expensive.\n     */\n    getRecursiveLayers(options?: RecursiveRetrievalOptions): Sublayer[];\n}\n\n/**\n * Union type for all layers (extending {@link LayerBaseType})\n */\nexport type Layer = SimpleLayer | WMSLayer | WMTSLayer | GroupLayer;\nexport type LayerTypes = Layer[\"type\"];\n\n/**\n * Union type for all sublayers (extending {@link SublayerBaseType}\n */\nexport type Sublayer = WMSSublayer;\nexport type SublayerTypes = Sublayer[\"type\"];\n\n/**\n * Union for all types of layers\n */\nexport type AnyLayer = Layer | Sublayer;\nexport type AnyLayerTypes = AnyLayer[\"type\"];\n\n/**\n * Type guard for checking if the layer is a {@link Sublayer}.\n */\nexport function isSublayer(layer: AnyLayer): layer is Sublayer {\n    return \"parentLayer\" in layer;\n}\n\n/**\n * Type guard for checking if the layer is a {@link Layer} (and not a {@link Sublayer}).\n */\nexport function isLayer(layer: AnyLayer): layer is Layer {\n    return \"olLayer\" in layer;\n}\n"],"names":[],"mappings":"AAqSO,SAAS,WAAW,KAAoC,EAAA;AAC3D,EAAA,OAAO,aAAiB,IAAA,KAAA;AAC5B;AAKO,SAAS,QAAQ,KAAiC,EAAA;AACrD,EAAA,OAAO,SAAa,IAAA,KAAA;AACxB;;;;"}
+{"version":3,"file":"base.js","sources":["base.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2023-2025 Open Pioneer project (https://github.com/open-pioneer)\n// SPDX-License-Identifier: Apache-2.0\nimport type { EventSource } from \"@open-pioneer/core\";\nimport type OlBaseLayer from \"ol/layer/Base\";\nimport type { MapModel } from \"../MapModel\";\nimport type { LayerRetrievalOptions, RecursiveRetrievalOptions } from \"../shared\";\nimport type { GroupLayer, GroupLayerCollection } from \"./GroupLayer\";\nimport type { SimpleLayer } from \"./SimpleLayer\";\nimport type { WMSLayer, WMSSublayer } from \"./WMSLayer\";\nimport type { WMTSLayer } from \"./WMTSLayer\";\n\n/** Events emitted by the {@link Layer} and other layer types. */\nexport interface LayerBaseEvents {\n    \"destroy\": void;\n}\n\n/** The load state of a layer. */\nexport type LayerLoadState = \"not-loaded\" | \"loading\" | \"loaded\" | \"error\";\n\n/** Custom function to check the state of a layer and returning a \"loaded\" or \"error\". */\nexport type HealthCheckFunction = (layer: Layer) => Promise<\"loaded\" | \"error\">;\n\n/**\n * Configuration options supported by all layer types (layers and sublayers).\n */\nexport interface LayerBaseConfig {\n    /**\n     * The unique id of this layer.\n     * Defaults to a generated id.\n     */\n    id?: string;\n\n    /**\n     * The human-readable title of this layer.\n     */\n    title: string;\n\n    /**\n     * The human-readable description of this layer.\n     * Defaults to an empty string.\n     */\n    description?: string;\n\n    /**\n     * Whether this layer should initially be visible.\n     * Defaults to `true`.\n     */\n    visible?: boolean;\n\n    /**\n     * Additional attributes for this layer.\n     * These can be arbitrary values.\n     */\n    attributes?: Record<string | symbol, unknown>;\n\n    /**\n     * Layers marked as internal are not considered by any UI widget (e.g. Toc or Legend)\n     * Defaults to `false`\n     */\n    internal?: boolean;\n}\n\n/**\n * Interface shared by all layer types (operational layers and sublayers).\n *\n * Instances of this interface cannot be constructed directly; use a real layer\n * class such as {@link SimpleLayer} instead.\n */\nexport interface AnyLayerBaseType<AdditionalEvents = {}>\n    extends EventSource<LayerBaseEvents & AdditionalEvents> {\n    /**\n     * Identifies the type of this layer.\n     */\n    readonly type: AnyLayerTypes;\n\n    /** The map this layer belongs to. */\n    readonly map: MapModel;\n\n    /**\n     * The direct parent of this layer instance, used for sublayers or for layers in a group layer.\n     *\n     * The property shall be undefined if the layer is not a sublayer or member of a group layer.\n     */\n    readonly parent: AnyLayer | undefined;\n\n    /**\n     * The unique id of this layer within its map model.\n     *\n     * NOTE: layer ids may not be globally unique: layers that belong\n     * to different map models may have the same id.\n     */\n    readonly id: string;\n\n    /** The human-readable title of this layer. */\n    readonly title: string;\n\n    /** The human-readable description of this layer. May be empty. */\n    readonly description: string;\n\n    /**\n     * Whether the layer is visible or not.\n     *\n     * NOTE: The model's visible state may do more than influence the raw OpenLayers's visibility property.\n     * Future versions may completely remove invisible layers from the OpenLayer's map under some circumstances.\n     */\n    readonly visible: boolean;\n\n    /**\n     * Legend URL from the service capabilities, if available.\n     *\n     * Note: this property may be expanded upon in the future, e.g. to support more variants than just image URLs.\n     */\n    readonly legend: string | undefined;\n\n    /**\n     * The direct children of this layer.\n     *\n     * The children may either be a set of operational layers (e.g. for a group layer) or a set of sublayers, or `undefined`.\n     *\n     * See also {@link layers} and {@link sublayers}.\n     */\n    readonly children: ChildrenCollection<AnyLayer> | undefined;\n\n    /**\n     * If this layer is a group layer this property contains a collection of all layers that a members to the group.\n     *\n     * The property shall be `undefined` if it is not a group layer.\n     *\n     * The properties `layers` and `sublayers` are mutually exclusive.\n     */\n    readonly layers: GroupLayerCollection | undefined;\n\n    /**\n     * The collection of child sublayers for this layer. Sublayers are layers that cannot exist without an appropriate parent layer.\n     *\n     * Layers that can never have any sublayers may not have a `sublayers` collection.\n     *\n     * The properties `layers` and `sublayers` are mutually exclusive.\n     */\n    readonly sublayers: SublayersCollection | undefined;\n\n    /**\n     * Property that specifies if the layer is an \"internal\" layer. Internal layers are not considered by any UI widget (e.g. Toc or Legend).\n     * The internal state is independent of the layer's visibility which is determined by {@link visible}\n     *\n     * NOTE: Some UI widgets might use component specific attributes or props that have precedence over the internal property.\n     */\n    readonly internal: boolean;\n\n    /**\n     * Additional attributes associated with this layer.\n     */\n    readonly attributes: Readonly<Record<string | symbol, unknown>>;\n\n    /**\n     * Updates the title of this layer.\n     */\n    setTitle(newTitle: string): void;\n\n    /**\n     * Updates the description of this layer.\n     */\n    setDescription(newDescription: string): void;\n\n    /**\n     * Updates the visibility of this layer to the new value.\n     *\n     * NOTE: The visibility of base layers cannot be changed through this method.\n     * Call {@link LayerCollection.activateBaseLayer} instead.\n     */\n    setVisible(newVisibility: boolean): void;\n\n    /**\n     * Updates the internal property of this layer to the new value.\n     * @param newIsInternal\n     */\n    setInternal(newIsInternal: boolean): void;\n\n    /**\n     * Updates the attributes of this layer.\n     * Values in `newAttributes` are merged into the existing ones (i.e. via `Object.assign`).\n     */\n    updateAttributes(newAttributes: Record<string | symbol, unknown>): void;\n\n    /**\n     * Deletes the attribute of this layer.\n     */\n    deleteAttribute(deleteAttribute: string | symbol): void;\n}\n\n/**\n * Configuration options supported by all operational layer types.\n */\nexport interface LayerConfig extends LayerBaseConfig {\n    /**\n     * Whether this layer is a base layer or not.\n     * Only one base layer can be active at a time.\n     *\n     * Defaults to `false`.\n     */\n    isBaseLayer?: boolean;\n\n    /**\n     * Optional property to check the availability of the layer.\n     * It is possible to provide either a URL which indicates the state of the service (2xx response meaning \"ok\")\n     * or a {@link HealthCheckFunction} performing a custom check and returning the state.\n     */\n    healthCheck?: string | HealthCheckFunction;\n}\n\n/**\n * Represents an operational layer in the map.\n *\n * Instances of this interface cannot be constructed directly; use a real layer\n * class such as {@link SimpleLayer} instead.\n */\nexport interface LayerBaseType<AdditionalEvents = {}> extends AnyLayerBaseType<AdditionalEvents> {\n    /**\n     * Identifies the type of this layer.\n     */\n    readonly type: LayerTypes;\n\n    /**\n     * The load state of a layer.\n     */\n    readonly loadState: LayerLoadState;\n\n    /**\n     * The raw OpenLayers layer.\n     */\n    readonly olLayer: OlBaseLayer;\n\n    /**\n     * True if this layer is a base layer.\n     *\n     * Only one base layer can be visible at a time.\n     */\n    readonly isBaseLayer: boolean;\n}\n\n/**\n * Represents a sublayer of another layer.\n */\nexport interface SublayerBaseType extends AnyLayerBaseType {\n    /**\n     * Identifies the type of this sublayer.\n     */\n    readonly type: SublayerTypes;\n\n    /**\n     * The direct parent of this layer instance.\n     * This can either be the parent layer or another sublayer.\n     */\n    readonly parent: AnyLayer;\n\n    /**\n     * The parent layer that owns this sublayer.\n     */\n    readonly parentLayer: Layer;\n}\n\n/**\n * Contains the children of a layer.\n */\nexport interface ChildrenCollection<LayerType> {\n    /**\n     * Returns the items in this collection.\n     */\n    getItems(options?: LayerRetrievalOptions): LayerType[];\n}\n\n/**\n * Contains the sublayers that belong to a {@link Layer} or {@link Sublayer}.\n */\nexport interface SublayersCollection<SublayerType = Sublayer>\n    extends ChildrenCollection<SublayerType> {\n    /**\n     * Returns the child sublayers in this collection.\n     */\n    getSublayers(options?: LayerRetrievalOptions): SublayerType[];\n\n    /**\n     * Returns a list of all layers in the collection, including all children (recursively).\n     *\n     * > Note: This includes base layers by default (see `options.filter`).\n     * > Use the `\"base\"` or `\"operational\"` short hand values to filter by base layer or operational layers.\n     * >\n     * > If the collection contains many, deeply nested sublayers, this function could potentially be expensive.\n     */\n    getRecursiveLayers(options?: RecursiveRetrievalOptions): Sublayer[];\n}\n\n/**\n * Union type for all layers (extending {@link LayerBaseType})\n */\nexport type Layer = SimpleLayer | WMSLayer | WMTSLayer | GroupLayer;\nexport type LayerTypes = Layer[\"type\"];\n\n/**\n * Union type for all sublayers (extending {@link SublayerBaseType}\n */\nexport type Sublayer = WMSSublayer;\nexport type SublayerTypes = Sublayer[\"type\"];\n\n/**\n * Union for all types of layers\n */\nexport type AnyLayer = Layer | Sublayer;\nexport type AnyLayerTypes = AnyLayer[\"type\"];\n\n/**\n * Type guard for checking if the layer is a {@link Sublayer}.\n */\nexport function isSublayer(layer: AnyLayer): layer is Sublayer {\n    return \"parentLayer\" in layer;\n}\n\n/**\n * Type guard for checking if the layer is a {@link Layer} (and not a {@link Sublayer}).\n */\nexport function isLayer(layer: AnyLayer): layer is Layer {\n    return \"olLayer\" in layer;\n}\n"],"names":[],"mappings":"AAyTO,SAAS,WAAW,KAAA,EAAoC;AAC3D,EAAA,OAAO,aAAA,IAAiB,KAAA;AAC5B;AAKO,SAAS,QAAQ,KAAA,EAAiC;AACrD,EAAA,OAAO,SAAA,IAAa,KAAA;AACxB;;;;"}

package/api/shared.d.ts

@@ -25,15 +25,16 @@ export interface AddLayerOptionsBase {
      *
      * Default: "top"
      *
-     * - "top": Insert the new layer _above_ all other operational layers.
+     * - "top": Insert the new layer _above_ all other *normal* operational layers (note: still below `"topmost"` layers).
      * - "bottom": Insert the new layer _below_ all other operational layers.
      * - "above": Insert the new layer _above_ the specified `reference` layer.
      * - "below": Insert the new layer _below_ the specified `reference` layer.
+     * - "topmost": Insert a new layer that is always displayed on top of all layers that were added at `top` (e.g. a highlight layer).
      */
-    at: "top" | "bottom" | "above" | "below";
+    at: "top" | "bottom" | "above" | "below" | "topmost";
 }
 export interface AddLayerOptionsTopBottom extends AddLayerOptionsBase {
-    at: "top" | "bottom";
+    at: "top" | "bottom" | "topmost";
 }
 export interface AddLayerOptionsAboveBelow extends AddLayerOptionsBase {
     at: "above" | "below";
@@ -42,7 +43,8 @@ export interface AddLayerOptionsAboveBelow extends AddLayerOptionsBase {
      *
      * Can be specified either as a layer object or an `id`.
      *
-     * The reference must be a valid layer in the layer collection.
+     * The reference must be a top level operational layer in the layer collection.
+     * Otherwise an error will be thrown.
      */
     reference: Layer | string;
 }

package/index.js

@@ -6,7 +6,7 @@ export { GroupLayer } from './api/layers/GroupLayer.js';
 export { getProjection, registerProjections } from './projections.js';
 export { MapAnchor } from './ui/MapAnchor.js';
 export { MapContainer } from './ui/MapContainer.js';
-export { useMapModel } from './ui/useMapModel.js';
+export { useMapModel, useMapModelValue } from './ui/useMapModel.js';
 export { DefaultMapProvider } from './ui/DefaultMapProvider.js';
 export { calculateBufferedExtent } from './util/geometry-utils.js';
 export { TOPMOST_LAYER_Z } from './model/LayerCollectionImpl.js';

package/model/AbstractLayer.js.map

@@ -1 +1 @@
-{"version":3,"file":"AbstractLayer.js","sources":["AbstractLayer.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2023-2025 Open Pioneer project (https://github.com/open-pioneer)\n// SPDX-License-Identifier: Apache-2.0\nimport { ExternalReactive, reactive, external, Reactive } from \"@conterra/reactivity-core\";\nimport { createLogger, destroyResource, Resource } from \"@open-pioneer/core\";\nimport { unByKey } from \"ol/Observable\";\nimport { EventsKey } from \"ol/events\";\nimport OlBaseLayer from \"ol/layer/Base\";\nimport OlLayer from \"ol/layer/Layer\";\nimport OlSource from \"ol/source/Source\";\nimport {\n    HealthCheckFunction,\n    Layer,\n    LayerBaseType,\n    LayerConfig,\n    LayerLoadState,\n    SimpleLayerConfig\n} from \"../api\";\nimport { AbstractLayerBase } from \"./AbstractLayerBase\";\nimport { MapModelImpl } from \"./MapModelImpl\";\n\nconst LOG = createLogger(\"map:AbstractLayer\");\n\n/**\n * Base class for normal layer types.\n *\n * These layers always have an associated OpenLayers layer.\n */\nexport abstract class AbstractLayer<AdditionalEvents = {}>\n    extends AbstractLayerBase<AdditionalEvents>\n    implements LayerBaseType\n{\n    #olLayer: OlBaseLayer;\n    #isBaseLayer: boolean;\n    #healthCheck?: string | HealthCheckFunction;\n\n    #visible: ExternalReactive<boolean>;\n    #loadState: Reactive<LayerLoadState>;\n\n    #visibilityWatchKey: EventsKey | undefined;\n    #stateWatchResource: Resource | undefined;\n\n    constructor(config: SimpleLayerConfig) {\n        super(config);\n        this.#olLayer = config.olLayer;\n        this.#isBaseLayer = config.isBaseLayer ?? false;\n        this.#healthCheck = config.healthCheck;\n\n        this.#visible = external(() => this.#olLayer.getVisible());\n        this.#visibilityWatchKey = this.#olLayer.on(\"change:visible\", this.#visible.trigger);\n\n        this.#loadState = reactive(getSourceState(getSource(this.#olLayer)));\n        this.__setVisible(config.visible ?? true); // apply initial visibility\n    }\n\n    get visible(): boolean {\n        return this.#visible.value;\n    }\n\n    get olLayer(): OlBaseLayer {\n        return this.#olLayer;\n    }\n\n    get isBaseLayer(): boolean {\n        return this.#isBaseLayer;\n    }\n\n    get loadState(): LayerLoadState {\n        return this.#loadState.value;\n    }\n\n    destroy() {\n        if (this.__destroyed) {\n            return;\n        }\n\n        this.#stateWatchResource = destroyResource(this.#stateWatchResource);\n        this.#visibilityWatchKey && unByKey(this.#visibilityWatchKey);\n        this.#visibilityWatchKey = undefined;\n        this.olLayer.dispose();\n        super.destroy();\n    }\n\n    /**\n     * Called by the map model when the layer is added to the map.\n     */\n    __attachToMap(map: MapModelImpl): void {\n        super.__attachToMap(map);\n\n        const { initial: initialState, resource: stateWatchResource } = watchLoadState(\n            this,\n            this.#healthCheck,\n            (state) => {\n                this.#loadState.value = state;\n            }\n        );\n        this.#stateWatchResource = stateWatchResource;\n        this.#loadState.value = initialState;\n    }\n\n    setVisible(newVisibility: boolean): void {\n        if (this.isBaseLayer) {\n            LOG.warn(\n                `Cannot change visibility of base layer '${this.id}': use activateBaseLayer() on the map's LayerCollection instead.`\n            );\n            return;\n        }\n\n        this.__setVisible(newVisibility);\n    }\n\n    __setVisible(newVisibility: boolean): void {\n        if (this.#olLayer.getVisible() !== newVisibility) {\n            this.#olLayer.setVisible(newVisibility);\n        }\n    }\n\n    abstract readonly type: \"simple\" | \"wms\" | \"wmts\" | \"group\";\n}\n\nfunction watchLoadState(\n    layer: AbstractLayer,\n    healthCheck: LayerConfig[\"healthCheck\"],\n    onChange: (newState: LayerLoadState) => void\n): { initial: LayerLoadState; resource: Resource } {\n    const olLayer = layer.olLayer;\n\n    if (!(olLayer instanceof OlLayer)) {\n        // Some layers don't have a source (such as group)\n        return {\n            initial: \"loaded\",\n            resource: {\n                destroy() {\n                    void 0;\n                }\n            }\n        };\n    }\n\n    let currentSource = getSource(olLayer);\n    const currentOlLayerState = getSourceState(currentSource);\n\n    let currentLoadState: LayerLoadState = currentOlLayerState;\n    let currentHealthState = \"loading\"; // initial state loading until health check finished\n\n    // custom health check not needed when OpenLayers already returning an error state\n    if (currentOlLayerState !== \"error\") {\n        // health check only once during initialization\n        doHealthCheck(layer, healthCheck).then((state: LayerLoadState) => {\n            currentHealthState = state;\n            updateState();\n        });\n    }\n\n    const updateState = () => {\n        const olLayerState = getSourceState(currentSource);\n        const nextLoadState: LayerLoadState =\n            currentHealthState === \"error\" ? \"error\" : olLayerState;\n\n        if (currentLoadState !== nextLoadState) {\n            currentLoadState = nextLoadState;\n            onChange(currentLoadState);\n        }\n    };\n\n    let stateHandle: EventsKey | undefined;\n    stateHandle = currentSource?.on(\"change\", () => {\n        updateState();\n    });\n\n    const sourceHandle = olLayer.on(\"change:source\", () => {\n        // unsubscribe from old source\n        stateHandle && unByKey(stateHandle);\n        stateHandle = undefined;\n\n        // subscribe to new source and update state\n        currentSource = getSource(olLayer);\n        stateHandle = currentSource?.on(\"change\", () => {\n            updateState();\n        });\n        updateState();\n    });\n    return {\n        initial: currentLoadState,\n        resource: {\n            destroy() {\n                stateHandle && unByKey(stateHandle);\n                unByKey(sourceHandle);\n            }\n        }\n    };\n}\n\nasync function doHealthCheck(\n    layer: AbstractLayer,\n    healthCheck: LayerConfig[\"healthCheck\"]\n): Promise<LayerLoadState> {\n    if (healthCheck == null) {\n        return \"loaded\";\n    }\n\n    let healthCheckFn: HealthCheckFunction;\n    if (typeof healthCheck === \"function\") {\n        healthCheckFn = healthCheck;\n    } else if (typeof healthCheck === \"string\") {\n        healthCheckFn = async () => {\n            const httpService = layer.map.__sharedDependencies.httpService;\n            const response = await httpService.fetch(healthCheck);\n            if (response.ok) {\n                return \"loaded\";\n            }\n            LOG.warn(\n                `Health check failed for layer '${layer.id}' (http status ${response.status})`\n            );\n            return \"error\";\n        };\n    } else {\n        LOG.error(\n            `Unexpected object for 'healthCheck' parameter of layer '${layer.id}'`,\n            healthCheck\n        );\n        return \"error\";\n    }\n\n    try {\n        return await healthCheckFn(layer as Layer);\n    } catch (e) {\n        LOG.warn(`Health check failed for layer '${layer.id}'`, e);\n        return \"error\";\n    }\n}\n\nfunction getSource(olLayer: OlLayer | OlBaseLayer) {\n    if (!(olLayer instanceof OlLayer)) {\n        return undefined;\n    }\n    return (olLayer?.getSource() as OlSource | null) ?? undefined;\n}\n\nfunction getSourceState(olSource: OlSource | undefined) {\n    const state = olSource?.getState();\n    switch (state) {\n        case undefined:\n            return \"loaded\";\n        case \"undefined\":\n            return \"not-loaded\";\n        case \"loading\":\n            return \"loading\";\n        case \"ready\":\n            return \"loaded\";\n        case \"error\":\n            return \"error\";\n    }\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"AbstractLayer.js","sources":["AbstractLayer.ts"],"sourcesContent":["// SPDX-FileCopyrightText: 2023-2025 Open Pioneer project (https://github.com/open-pioneer)\n// SPDX-License-Identifier: Apache-2.0\nimport { ExternalReactive, reactive, external, Reactive } from \"@conterra/reactivity-core\";\nimport { createLogger, destroyResource, Resource } from \"@open-pioneer/core\";\nimport { unByKey } from \"ol/Observable\";\nimport { EventsKey } from \"ol/events\";\nimport OlBaseLayer from \"ol/layer/Base\";\nimport OlLayer from \"ol/layer/Layer\";\nimport OlSource from \"ol/source/Source\";\nimport {\n    HealthCheckFunction,\n    Layer,\n    LayerBaseType,\n    LayerConfig,\n    LayerLoadState,\n    SimpleLayerConfig\n} from \"../api\";\nimport { AbstractLayerBase } from \"./AbstractLayerBase\";\nimport { MapModelImpl } from \"./MapModelImpl\";\n\nconst LOG = createLogger(\"map:AbstractLayer\");\n\n/**\n * Base class for normal layer types.\n *\n * These layers always have an associated OpenLayers layer.\n */\nexport abstract class AbstractLayer<AdditionalEvents = {}>\n    extends AbstractLayerBase<AdditionalEvents>\n    implements LayerBaseType\n{\n    #olLayer: OlBaseLayer;\n    #isBaseLayer: boolean;\n    #healthCheck?: string | HealthCheckFunction;\n\n    #visible: ExternalReactive<boolean>;\n    #loadState: Reactive<LayerLoadState>;\n\n    #visibilityWatchKey: EventsKey | undefined;\n    #stateWatchResource: Resource | undefined;\n\n    constructor(config: SimpleLayerConfig) {\n        super(config);\n        this.#olLayer = config.olLayer;\n        this.#isBaseLayer = config.isBaseLayer ?? false;\n        this.#healthCheck = config.healthCheck;\n\n        this.#visible = external(() => this.#olLayer.getVisible());\n        this.#visibilityWatchKey = this.#olLayer.on(\"change:visible\", this.#visible.trigger);\n\n        this.#loadState = reactive(getSourceState(getSource(this.#olLayer)));\n        this.__setVisible(config.visible ?? true); // apply initial visibility\n    }\n\n    get visible(): boolean {\n        return this.#visible.value;\n    }\n\n    get olLayer(): OlBaseLayer {\n        return this.#olLayer;\n    }\n\n    get isBaseLayer(): boolean {\n        return this.#isBaseLayer;\n    }\n\n    get loadState(): LayerLoadState {\n        return this.#loadState.value;\n    }\n\n    destroy() {\n        if (this.__destroyed) {\n            return;\n        }\n\n        this.#stateWatchResource = destroyResource(this.#stateWatchResource);\n        this.#visibilityWatchKey && unByKey(this.#visibilityWatchKey);\n        this.#visibilityWatchKey = undefined;\n        this.olLayer.dispose();\n        super.destroy();\n    }\n\n    /**\n     * Called by the map model when the layer is added to the map.\n     */\n    __attachToMap(map: MapModelImpl): void {\n        super.__attachToMap(map);\n\n        const { initial: initialState, resource: stateWatchResource } = watchLoadState(\n            this,\n            this.#healthCheck,\n            (state) => {\n                this.#loadState.value = state;\n            }\n        );\n        this.#stateWatchResource = stateWatchResource;\n        this.#loadState.value = initialState;\n    }\n\n    setVisible(newVisibility: boolean): void {\n        if (this.isBaseLayer) {\n            LOG.warn(\n                `Cannot change visibility of base layer '${this.id}': use activateBaseLayer() on the map's LayerCollection instead.`\n            );\n            return;\n        }\n\n        this.__setVisible(newVisibility);\n    }\n\n    __setVisible(newVisibility: boolean): void {\n        if (this.#olLayer.getVisible() !== newVisibility) {\n            this.#olLayer.setVisible(newVisibility);\n        }\n    }\n\n    abstract readonly type: \"simple\" | \"wms\" | \"wmts\" | \"group\";\n}\n\nfunction watchLoadState(\n    layer: AbstractLayer,\n    healthCheck: LayerConfig[\"healthCheck\"],\n    onChange: (newState: LayerLoadState) => void\n): { initial: LayerLoadState; resource: Resource } {\n    const olLayer = layer.olLayer;\n\n    if (!(olLayer instanceof OlLayer)) {\n        // Some layers don't have a source (such as group)\n        return {\n            initial: \"loaded\",\n            resource: {\n                destroy() {\n                    void 0;\n                }\n            }\n        };\n    }\n\n    let currentSource = getSource(olLayer);\n    const currentOlLayerState = getSourceState(currentSource);\n\n    let currentLoadState: LayerLoadState = currentOlLayerState;\n    let currentHealthState = \"loading\"; // initial state loading until health check finished\n\n    // custom health check not needed when OpenLayers already returning an error state\n    if (currentOlLayerState !== \"error\") {\n        // health check only once during initialization\n        doHealthCheck(layer, healthCheck).then((state: LayerLoadState) => {\n            currentHealthState = state;\n            updateState();\n        });\n    }\n\n    const updateState = () => {\n        const olLayerState = getSourceState(currentSource);\n        const nextLoadState: LayerLoadState =\n            currentHealthState === \"error\" ? \"error\" : olLayerState;\n\n        if (currentLoadState !== nextLoadState) {\n            currentLoadState = nextLoadState;\n            onChange(currentLoadState);\n        }\n    };\n\n    let stateHandle: EventsKey | undefined;\n    stateHandle = currentSource?.on(\"change\", () => {\n        updateState();\n    });\n\n    const sourceHandle = olLayer.on(\"change:source\", () => {\n        // unsubscribe from old source\n        stateHandle && unByKey(stateHandle);\n        stateHandle = undefined;\n\n        // subscribe to new source and update state\n        currentSource = getSource(olLayer);\n        stateHandle = currentSource?.on(\"change\", () => {\n            updateState();\n        });\n        updateState();\n    });\n    return {\n        initial: currentLoadState,\n        resource: {\n            destroy() {\n                stateHandle && unByKey(stateHandle);\n                unByKey(sourceHandle);\n            }\n        }\n    };\n}\n\nasync function doHealthCheck(\n    layer: AbstractLayer,\n    healthCheck: LayerConfig[\"healthCheck\"]\n): Promise<LayerLoadState> {\n    if (healthCheck == null) {\n        return \"loaded\";\n    }\n\n    let healthCheckFn: HealthCheckFunction;\n    if (typeof healthCheck === \"function\") {\n        healthCheckFn = healthCheck;\n    } else if (typeof healthCheck === \"string\") {\n        healthCheckFn = async () => {\n            const httpService = layer.map.__sharedDependencies.httpService;\n            const response = await httpService.fetch(healthCheck);\n            if (response.ok) {\n                return \"loaded\";\n            }\n            LOG.warn(\n                `Health check failed for layer '${layer.id}' (http status ${response.status})`\n            );\n            return \"error\";\n        };\n    } else {\n        LOG.error(\n            `Unexpected object for 'healthCheck' parameter of layer '${layer.id}'`,\n            healthCheck\n        );\n        return \"error\";\n    }\n\n    try {\n        return await healthCheckFn(layer as Layer);\n    } catch (e) {\n        LOG.warn(`Health check failed for layer '${layer.id}'`, e);\n        return \"error\";\n    }\n}\n\nfunction getSource(olLayer: OlLayer | OlBaseLayer) {\n    if (!(olLayer instanceof OlLayer)) {\n        return undefined;\n    }\n    return (olLayer?.getSource() as OlSource | null) ?? undefined;\n}\n\nfunction getSourceState(olSource: OlSource | undefined) {\n    const state = olSource?.getState();\n    switch (state) {\n        case undefined:\n            return \"loaded\";\n        case \"undefined\":\n            return \"not-loaded\";\n        case \"loading\":\n            return \"loading\";\n        case \"ready\":\n            return \"loaded\";\n        case \"error\":\n            return \"error\";\n    }\n}\n"],"names":[],"mappings":"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"}

package/model/AbstractLayerBase.d.ts

@@ -9,6 +9,7 @@ export interface AbstractLayerBaseOptions {
     title: string;
     description?: string;
     attributes?: Record<string, unknown>;
+    internal?: boolean;
 }
 /**
  * Base class for "normal" layers and sublayers alike to implement common properties
@@ -17,6 +18,8 @@ export interface AbstractLayerBaseOptions {
 export declare abstract class AbstractLayerBase<AdditionalEvents = {}> extends EventEmitter<LayerBaseEvents & AdditionalEvents> implements AnyLayerBaseType {
     #private;
     constructor(config: AbstractLayerBaseOptions);
+    get internal(): boolean;
+    setInternal(newIsInternal: boolean): void;
     protected get __destroyed(): boolean;
     get map(): MapModelImpl;
     get id(): string;

package/model/AbstractLayerBase.js

@@ -12,6 +12,7 @@ class AbstractLayerBase extends EventEmitter {
   #attributesMap = reactiveMap();
   #attributes;
   #destroyed = false;
+  #internal;
   constructor(config) {
     super();
     this.#id = config.id ?? v4();
@@ -20,10 +21,17 @@ class AbstractLayerBase extends EventEmitter {
     });
     this.#title = reactive(config.title);
     this.#description = reactive(config.description ?? "");
+    this.#internal = reactive(config.internal ?? false);
     if (config.attributes) {
       this.updateAttributes(config.attributes);
     }
   }
+  get internal() {
+    return this.#internal.value;
+  }
+  setInternal(newIsInternal) {
+    this.#internal.value = newIsInternal;
+  }
   get __destroyed() {
     return this.#destroyed;
   }