@vcmap/ui 5.0.2 → 5.1.0-rc.2

package/src/pluginHelper.js

@@ -32,6 +32,7 @@ export const pluginBaseUrlSymbol = Symbol('pluginBaseUrl');
  * @type {symbol}
  */
 export const pluginModuleUrlSymbol = Symbol('pluginModuleUrl');
+
 /**
  * A symbol added to each plugin which describes the configured version range
  * @type {symbol}
@@ -43,7 +44,7 @@ export const pluginVersionRangeSymbol = Symbol('pluginVersionRange');
  * shipping your plugin with a "plugin-asset/icon.png", you can always retrieve said icon with getPluginAssetUrl(app, name, 'pluing-assets/icon.png')
  * Sets the plugin version as searchParam.
  * Returns null, if the plugin does not exist.
- * @param {VcsUiApp} app
+ * @param {import("@src/vcsUiApp.js").default} app
  * @param {string} pluginName
  * @param {string} asset
  * @returns {string|null}
@@ -83,8 +84,10 @@ export function isValidPackageName(name) {
 
 /**
  * @param {string} name
- * @param {PluginConfig} config
- * @returns {Promise<VcsPlugin|null>}
+ * @param {T} config
+ * @returns {Promise<import("@src/vcsUiApp.js").VcsPlugin<T, S>|null>}
+ * @template {Object} T
+ * @template {Object} S
  */
 export async function loadPlugin(name, config) {
   let module = config.entry;
@@ -97,7 +100,7 @@ export async function loadPlugin(name, config) {
   } else if (module === '_dev') {
     module = `/${name}.js`;
   } else if (module === 'http://localhost/_test') {
-    // early escape to bypass module loading for testing, see VcsUiApp.spec.js
+    // early escape to bypass module loading for testing, see import("@src/vcsUiApp.js").default.spec.js
     return null;
   }
   if (config.version) {
@@ -193,7 +196,7 @@ export function getPluginEntry(base, pluginUrl) {
 }
 
 /**
- * @param {VcsPlugin} plugin
+ * @param {import("@src/vcsUiApp.js").VcsPlugin<Object, Object>} plugin
  * @returns {Object}
  */
 export function serializePlugin(plugin) {
@@ -215,13 +218,12 @@ export function serializePlugin(plugin) {
 
 /**
  * @param {Object} serializedPlugin
- * @returns {Promise<VcsPlugin|null>}
+ * @returns {Promise<import("@src/vcsUiApp.js").VcsPlugin<Object, Object>|null>}
  */
 export async function deserializePlugin(serializedPlugin) {
   if (serializedPlugin[pluginFactorySymbol]) {
-    const reincarnation = await serializedPlugin[pluginFactorySymbol](
-      serializedPlugin,
-    );
+    const reincarnation =
+      await serializedPlugin[pluginFactorySymbol](serializedPlugin);
     reincarnation[pluginFactorySymbol] = serializedPlugin[pluginFactorySymbol];
     reincarnation[pluginBaseUrlSymbol] = serializedPlugin[pluginBaseUrlSymbol];
     reincarnation[pluginModuleUrlSymbol] =

package/src/search/ResultItem.vue.d.ts

@@ -0,0 +1,25 @@
+declare const _default: import("vue").DefineComponent<{
+    query: {
+        type: StringConstructor;
+        default: string;
+    };
+    item: {
+        type: ObjectConstructor;
+        required: true;
+    };
+}, {
+    hasActions: import("vue").ComputedRef<boolean>;
+    marked: import("vue").ComputedRef<string>;
+}, {}, {}, {}, import("vue/types/v3-component-options.js").ComponentOptionsMixin, import("vue/types/v3-component-options.js").ComponentOptionsMixin, {}, string, Readonly<import("vue").ExtractPropTypes<{
+    query: {
+        type: StringConstructor;
+        default: string;
+    };
+    item: {
+        type: ObjectConstructor;
+        required: true;
+    };
+}>>, {
+    query: string;
+}>;
+export default _default;

package/src/search/ResultsComponent.vue

@@ -54,7 +54,7 @@
     },
     setup(props) {
       const highlightedRef = ref(-1);
-      /** @type {VcsUiApp} */
+      /** @type {import("@src/vcsUiApp.js").default} */
       const app = inject('vcsApp');
       const selectedListener = app.featureInfo.featureChanged.addEventListener(
         (feature) => {

package/src/search/ResultsComponent.vue.d.ts

@@ -0,0 +1,24 @@
+declare const _default: import("vue").DefineComponent<{
+    query: {
+        type: StringConstructor;
+        default: string;
+    };
+    results: {
+        type: ArrayConstructor;
+        required: true;
+    };
+}, {
+    highlighted: import("vue").WritableComputedRef<number>;
+}, {}, {}, {}, import("vue/types/v3-component-options.js").ComponentOptionsMixin, import("vue/types/v3-component-options.js").ComponentOptionsMixin, {}, string, Readonly<import("vue").ExtractPropTypes<{
+    query: {
+        type: StringConstructor;
+        default: string;
+    };
+    results: {
+        type: ArrayConstructor;
+        required: true;
+    };
+}>>, {
+    query: string;
+}>;
+export default _default;

package/src/search/SearchComponent.vue

@@ -65,7 +65,7 @@
       VDivider,
     },
     setup() {
-      /** @type {VcsUiApp} */
+      /** @type {import("@src/vcsUiApp.js").default} */
       const app = inject('vcsApp');
       const searching = ref(false);
       const query = ref(null);

package/src/search/SearchComponent.vue.d.ts

@@ -0,0 +1,10 @@
+declare const _default: import("vue").DefineComponent<{}, {
+    query: import("vue").Ref<null>;
+    searching: import("vue").Ref<boolean>;
+    results: import("vue").Ref<import("./search.js").ResultItem[]>;
+    reset: () => void;
+    clear: () => void;
+    search: () => Promise<void>;
+    zoomToAll: () => void;
+}, {}, {}, {}, import("vue/types/v3-component-options.js").ComponentOptionsMixin, import("vue/types/v3-component-options.js").ComponentOptionsMixin, {}, string, Readonly<import("vue").ExtractPropTypes<{}>>, {}>;
+export default _default;

package/src/search/search.d.ts

@@ -0,0 +1,129 @@
+export default Search;
+/**
+ * A readonly rendering interface of a ResultItem.
+ * A ResultItem must provide either a feature, a clicked handler or both.
+ */
+export type ResultItem = {
+    title: string;
+    /**
+     * An optional icon
+     */
+    icon?: string | undefined;
+    actions?: import("../actions/actionHelper.js").VcsAction[] | undefined;
+    /**
+     * Obligatory, if no feature is provided. Can overwrite default zoom to feature behaviour.
+     */
+    clicked?: (() => Promise<void>) | undefined;
+    /**
+     * If a feature is provided, the feature is added to the result layer and search zooms to the layer's extent. Default clicked handler is zoom to feature, highlight feature and select feature, if feature has a FeatureInfoView.
+     */
+    feature?: import("ol").Feature | undefined;
+};
+export type SearchImpl = {
+    /**
+     * Name of the implementation. Must be the name of the plugin the SearchImpl is owned by
+     */
+    name: string;
+    search: (arg0: string) => Array<ResultItem>;
+    suggest?: ((arg0: string) => Array<string>) | undefined;
+    /**
+     * - should abort any ongoing requests to search or suggest without throwing an error
+     */
+    abort: () => void;
+    destroy: () => void;
+};
+/**
+ * Collection of SearchImpl
+ * @extends {IndexedCollection<SearchImpl>}
+ */
+declare class Search extends IndexedCollection<SearchImpl> {
+    /**
+     * @param {import("@src/vcsUiApp.js").default} app
+     */
+    constructor(app: import("@src/vcsUiApp.js").default);
+    /**
+     * @type {import("@src/vcsUiApp.js").default}
+     * @private
+     */
+    private _app;
+    /**
+     * An event triggered every time the currentResults array changes,
+     * either by a new search providing the new results or
+     * on clearing, if the results array has not been empty already.
+     * @type {import("@vcmap/core").VcsEvent<Array<ResultItem>>}
+     * @private
+     */
+    private _resultsChanged;
+    /**
+     * @type {import("vue").Ref<Array<ResultItem>>}
+     * @private
+     */
+    private _currentResults;
+    /**
+     * @type {import("@vcmap/core").VectorLayer}
+     * @private
+     */
+    private _resultLayer;
+    /**
+     * @type {function():void}
+     * @private
+     */
+    private _destroyResultLayer;
+    /**
+     * An event triggered every time the currentResults array changes,
+     * either by a new search providing the new results or
+     * on clearing, if the results array has not been empty already.
+     * @type {import("@vcmap/core").VcsEvent<Array<ResultItem>>}
+     */
+    get resultsChanged(): VcsEvent<ResultItem[]>;
+    /**
+     * @type {import("vue").Ref<Array<ResultItem>>}
+     */
+    get currentResults(): import("vue").Ref<ResultItem[]>;
+    /**
+     * @type {VectorLayer}
+     */
+    get resultLayer(): VectorLayer;
+    /**
+     * @param {SearchImpl} item
+     * @param {string|symbol} owner pluginName or vcsAppSymbol
+     * @param {number=} index
+     */
+    // @ts-ignore
+add(item: SearchImpl, owner: string | symbol, index?: number | undefined): void;
+    /**
+     * removes all search implementations of a specific owner (plugin) and fires removed Events
+     * @param {string|vcsAppSymbol} owner
+     */
+    removeOwner(owner: string | symbol): void;
+    /**
+     * Get the results for a given query string.
+     * Available features are added to results layer and map is zoomed to all results (extent of result layer).
+     * Adds default clicked handler to result items with feature, which zooms to and highlights said feature. If feature has FeatureInfoView, feature is selected by featureInfo.
+     * @param {string} q
+     * @returns {Promise<Array<ResultItem>>}
+     */
+    search(q: string): Promise<Array<ResultItem>>;
+    /**
+     * Get the suggestions for a given query string
+     * @param {string} q
+     * @returns {Promise<Array<string>>}
+     */
+    suggest(q: string): Promise<Array<string>>;
+    /**
+     * Aborting any ongoing request
+     */
+    abort(): void;
+    /**
+     * Zooms to the extent of all available result features
+     * @returns {Promise<void>}
+     */
+    zoomToAll(): Promise<void>;
+    /**
+     * Clears the results and aborts running request
+     */
+    clearResults(): void;
+}
+import { IndexedCollection } from '@vcmap/core';
+import { VcsEvent } from '@vcmap/core';
+import { VectorLayer } from '@vcmap/core';

package/src/search/search.js

@@ -26,16 +26,16 @@ import { getViewpointFromFeature } from '../actions/actionHelper.js';
  * @typedef {Object} ResultItem
  * @property {string} title
  * @property {string} [icon] An optional icon
- * @property {Array<VcsAction>} [actions]
+ * @property {Array<import("../actions/actionHelper.js").VcsAction>} [actions]
  * @property {function():Promise<void>} [clicked] Obligatory, if no feature is provided. Can overwrite default zoom to feature behaviour.
  * @property {import("ol").Feature|undefined} [feature] If a feature is provided, the feature is added to the result layer and search zooms to the layer's extent. Default clicked handler is zoom to feature, highlight feature and select feature, if feature has a FeatureInfoView.
  */
 
 /**
- * @interface SearchImpl
+ * @typedef {Object} SearchImpl
  * @property {string} name Name of the implementation. Must be the name of the plugin the SearchImpl is owned by
- * @property {function(q:string):Array<ResultItem>} search
- * @property {function(q:string):Array<string>} [suggest] // XXX currently not implemented in UI at Beta state
+ * @property {function(string):Array<ResultItem>} search
+ * @property {function(string):Array<string>} [suggest] // XXX currently not implemented in UI at Beta state
  * @property{function():void} abort - should abort any ongoing requests to search or suggest without throwing an error
  * @property {function():void} destroy
  */
@@ -56,7 +56,7 @@ function getPointResultIcon(color) {
 
 /**
  * sets up result layer for displaying search results
- * @param {VcsUiApp} app
+ * @param {import("@src/vcsUiApp.js").default} app
  * @returns {{ resultLayer: import("@vcmap/core").VectorLayer, destroy: (function(): void)}}
  */
 function setupSearchResultLayer(app) {
@@ -111,17 +111,17 @@ const searchImplOwnerSymbol = Symbol('featureInfoView');
 
 /**
  * Collection of SearchImpl
- * @extends {IndexedCollection<SearchImpl<ResultItem>>}
+ * @extends {IndexedCollection<SearchImpl>}
  */
 class Search extends IndexedCollection {
   /**
-   * @param {VcsUiApp} app
+   * @param {import("@src/vcsUiApp.js").default} app
    */
   constructor(app) {
     super();
 
     /**
-     * @type {VcsUiApp}
+     * @type {import("@src/vcsUiApp.js").default}
      * @private
      */
     this._app = app;
@@ -158,7 +158,6 @@ class Search extends IndexedCollection {
    * either by a new search providing the new results or
    * on clearing, if the results array has not been empty already.
    * @type {import("@vcmap/core").VcsEvent<Array<ResultItem>>}
-   * @readonly
    */
   get resultsChanged() {
     return this._resultsChanged;
@@ -166,7 +165,6 @@ class Search extends IndexedCollection {
 
   /**
    * @type {import("vue").Ref<Array<ResultItem>>}
-   * @readonly
    */
   get currentResults() {
     return this._currentResults;
@@ -174,7 +172,6 @@ class Search extends IndexedCollection {
 
   /**
    * @type {VectorLayer}
-   * @readonly
    */
   get resultLayer() {
     return this._resultLayer;

package/src/setup.d.ts

@@ -0,0 +1 @@
+export {};

package/src/state.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @returns {AppState}
+ */
+export function createEmptyState(): AppState;
+/**
+ * @param {(URL)=} url
+ * @returns {AppState}
+ */
+export function getStateFromURL(url?: (URL) | undefined): AppState;
+/**
+ * @param {AppState} state
+ * @param {URL} url - sets the query parameter "state" on this URL
+ */
+export function setStateToUrl(state: AppState, url: URL): void;
+export type LayerState = {
+    name: string;
+    active: boolean;
+    styleName?: string | undefined;
+};
+/**
+ * The URL state of a layer is an array. The first entry is the layer name,
+ * the second its active state encoded in an integer (1 active, 0 inactive),
+ * the third and optional entry, is an optional styleName to set on the layer
+ */
+export type UrlLayerState = [string, number, string | 0];
+export type PluginState<T> = {
+    name: string;
+    state: T;
+};
+/**
+ * The URL state of a plugin is an array. The first entry is the plugin name, the second entry is
+ * an encoded object, which is the plugins state.
+ */
+export type UrlPluginState = [string, unknown];
+/**
+ * The URL state of a viewpoint is an array, the first entry is the camera position (or 0)
+ * the second is the ground position (or 0), the third is the distance, the last three are
+ * heading, pitch, roll in that order
+ */
+export type UrlViewpointState = [Array<number> | 0, Array<number> | 0, number, number, number, number];
+export type AppState = {
+    activeViewpoint?: import("@vcmap/core").ViewpointOptions | undefined;
+    activeMap?: string | undefined;
+    moduleIds: Array<string>;
+    layers: Array<LayerState>;
+    plugins: Array<PluginState<unknown>>;
+    activeObliqueCollection?: string | undefined;
+};
+/**
+ * The URL state of the app is an array. To null parameters, pass in 0 instead.
+ * The first entry is the viewpoint state, the second the active map name
+ * The third is an array of modules to apply the state to
+ * the fourth is an array of layer states
+ * the fifth is an array of plugin states
+ * the sixth is the currently active oblique collection or 0 if not applicable
+ */
+export type UrlAppState = [[0 | number[], 0 | number[], number, number, number, number], string, Array<string>, Array<[string, number, string | 0]>, Array<[string, unknown]>, (string | 0)];

package/src/state.js

@@ -17,15 +17,17 @@ import { Viewpoint } from '@vcmap/core';
  */
 
 /**
- * @typedef {Object} PluginState
- * @property {string} name
- * @property {*} state
+ * @typedef {{
+ *   name: string,
+ *   state: T
+ * }} PluginState
+ * @template T
  */
 
 /**
  * The URL state of a plugin is an array. The first entry is the plugin name, the second entry is
  * an encoded object, which is the plugins state.
- * @typedef {[string, *]} UrlPluginState
+ * @typedef {[string, unknown]} UrlPluginState
  */
 
 /**
@@ -41,7 +43,7 @@ import { Viewpoint } from '@vcmap/core';
  * @property {string} [activeMap]
  * @property {Array<string>} moduleIds
  * @property {Array<LayerState>} layers
- * @property {Array<PluginState>} plugins
+ * @property {Array<PluginState<unknown>>} plugins
  * @property {string} [activeObliqueCollection]
  */
 

package/src/uiConfig.d.ts

@@ -0,0 +1,99 @@
+export default UiConfig;
+export type UiConfigurationItem<T> = {
+    name: string;
+    value: T;
+};
+export type TextPageType = {
+    title: string;
+    url?: string | URL | undefined;
+    content?: string | undefined;
+};
+export type UiConfigObject = {
+    /**
+     * - the company logo to display. this will override any and all css overrides.
+     */
+    logo?: string | undefined;
+    /**
+     * - an alternative logo to display in mobile view
+     */
+    mobileLogo?: string | undefined;
+    /**
+     * - an optional title to display next to the company logo
+     */
+    appTitle?: string | undefined;
+    /**
+     * - an optional primary color to use in all themes
+     */
+    primaryColor?: string | undefined;
+    /**
+     * - an optional flag whether to activate feature info on startup (default active)
+     */
+    startingFeatureInfo?: boolean | undefined;
+    /**
+     * - mouse event, when position display is updated. Either 'click' (default) or 'move'.
+     */
+    positionDisplayEventType?: string | undefined;
+    /**
+     * - an optional URL to a help landing page
+     */
+    helpBaseUrl?: string | undefined;
+    /**
+     * - an option imprint, will show a link in the footer.
+     */
+    imprint?: TextPageType | undefined;
+    /**
+     * - an option dataProtection, will show a link in the footer.
+     */
+    dataProtection?: TextPageType | undefined;
+};
+/**
+ * @typedef {{
+ *   name: string,
+ *   value: T
+ * }} UiConfigurationItem
+ * @template T
+ */
+/**
+ * @typedef {Object} TextPageType
+ * @property {string} title
+ * @property {URL|string} [url]
+ * @property {string} [content]
+ */
+/**
+ * @typedef {Object} UiConfigObject
+ * @property {string} [logo] - the company logo to display. this will override any and all css overrides.
+ * @property {string} [mobileLogo] - an alternative logo to display in mobile view
+ * @property {string} [appTitle] - an optional title to display next to the company logo
+ * @property {string} [primaryColor] - an optional primary color to use in all themes
+ * @property {boolean} [startingFeatureInfo] - an optional flag whether to activate feature info on startup (default active)
+ * @property {string} [positionDisplayEventType] - mouse event, when position display is updated. Either 'click' (default) or 'move'.
+ * @property {string} [helpBaseUrl='https://help.vc.systems/'] - an optional URL to a help landing page
+ * @property {TextPageType} [imprint] - an option imprint, will show a link in the footer.
+ * @property {TextPageType} [dataProtection] - an option dataProtection, will show a link in the footer.
+ */
+/**
+ * @extends {Collection<UiConfigurationItem<unknown>>}
+ */
+declare class UiConfig extends Collection<UiConfigurationItem<unknown>> {
+    /**
+     * @param {function():string} getDynamicModuleId
+     */
+    constructor(getDynamicModuleId: () => string);
+    /**
+     * @type {import("vue").Ref<Object<string, *>>}
+     * @private
+     */
+    private _config;
+    /**
+     * @type {Array<function():void>}
+     * @private
+     */
+    private _listeners;
+    /**
+     * @type {import("vue").Ref<Object<string, unknown>|UiConfigObject>}
+     */
+    get config(): import("vue").Ref<{
+        [x: string]: unknown;
+    } | UiConfigObject>;
+}
+import { Collection } from '@vcmap/core';

package/src/uiConfig.js

@@ -2,9 +2,18 @@ import { Collection, makeOverrideCollection } from '@vcmap/core';
 import { ref } from 'vue';
 
 /**
- * @typedef {Object} UiConfigurationItem
- * @property {string} name
- * @property {*} value
+ * @typedef {{
+ *   name: string,
+ *   value: T
+ * }} UiConfigurationItem
+ * @template T
+ */
+
+/**
+ * @typedef {Object} TextPageType
+ * @property {string} title
+ * @property {URL|string} [url]
+ * @property {string} [content]
  */
 
 /**
@@ -14,13 +23,14 @@ import { ref } from 'vue';
  * @property {string} [appTitle] - an optional title to display next to the company logo
  * @property {string} [primaryColor] - an optional primary color to use in all themes
  * @property {boolean} [startingFeatureInfo] - an optional flag whether to activate feature info on startup (default active)
+ * @property {string} [positionDisplayEventType] - mouse event, when position display is updated. Either 'click' (default) or 'move'.
  * @property {string} [helpBaseUrl='https://help.vc.systems/'] - an optional URL to a help landing page
+ * @property {TextPageType} [imprint] - an option imprint, will show a link in the footer.
+ * @property {TextPageType} [dataProtection] - an option dataProtection, will show a link in the footer.
  */
 
 /**
- * @class
- * @extends {Collection<UiConfigurationItem>}
- * @implements {import("@vcmap/core").OverrideCollectionInterface<UiConfigurationItem>}
+ * @extends {Collection<UiConfigurationItem<unknown>>}
  */
 class UiConfig extends Collection {
   /**
@@ -62,7 +72,7 @@ class UiConfig extends Collection {
   }
 
   /**
-   * @returns {import("vue").Ref<Object<string, *>|UiConfigObject>}
+   * @type {import("vue").Ref<Object<string, unknown>|UiConfigObject>}
    */
   get config() {
     return this._config;