@mapsight/ui 7.0.0

package/src/js/index.ts

@@ -0,0 +1,319 @@
+import merge from "lodash/merge";
+import {applyMiddleware, compose} from "redux";
+import thunk from "redux-thunk";
+
+import {createMapsightStore} from "@mapsight/core";
+import {layerIdsExternalSwitcherSelector} from "@mapsight/core/lib/map/selectors";
+import {type State} from "@mapsight/core/types";
+
+import * as nonNull from "@mapsight/lib-js/nonNullable";
+import type {MapsightStyleFunction} from "@mapsight/lib-ol/style/styleFunction";
+
+import {siteConfig} from "./config";
+import {VIEW_MOBILE} from "./config/constants/app";
+import * as c from "./config/constants/controllers";
+import {createDefaultControllers} from "./controllers/defaults";
+import uiReducers from "./store/reducers";
+import type {
+	CreateOptions,
+	MapsightUiContext,
+	MapsightUiRenderer,
+	MapsightUiRendererProps,
+	MapsightUiStore,
+	PluginDefinition,
+	PluginPhase,
+} from "./types";
+
+/**
+ * Default mapsight ui renderer (Does nothing, but log a warning!).
+ */
+const defaultRenderer: MapsightUiRenderer<void> = (
+	_container,
+	_props,
+	_hydrate = false,
+) => {
+	console.info("create has to be passed a renderer to render the app");
+};
+
+// FIXME: What's the point in having this if it's all undefined?
+const defaultCreateOptions: CreateOptions = {
+	baseUrl: undefined,
+	imagesUrl: undefined,
+	// search
+	searchUrl: undefined,
+	searchQueryParameter: undefined,
+	reHydratedState: undefined,
+	uiState: {
+		isFullscreen: false,
+		listQuery: "",
+		listSorting: undefined,
+		listPage: 0, // current page
+		searchQuery: "",
+		searchResult: {},
+		searchResultSelectionFeatures: [],
+		title: "",
+		userPreferenceListVisible: true,
+		mapIsOutOfViewport: false,
+
+		// views
+		view: VIEW_MOBILE, // mobile first
+		viewBreakpoints: [],
+
+		embeddedMap: false, // map is embedded which switch some behaviours which would be annoying
+		searchInMap: true, // enable address search in map overlay
+
+		pageTitle: {
+			show: true, // show page title
+		},
+		tagSwitcher: {
+			show: false, // turn on tag switcher which will filter
+			featureSourceId: undefined,
+			featureSourcesControllerName: c.FEATURE_SOURCES,
+			toggleableGroups: false, // make group names (headers) buttons that toggle on/off groups
+			sortTags: false, // sort tags with locale sort, but not the tagGroups. to sort tagGroups add all tagGroups to first feature entry (but with empty tags if the entry doesn't have tags for a tagGroup)
+		},
+		viewToggle: {
+			show: true,
+			deselectFeaturesOnToggle: true,
+		},
+		layerSwitcher: {
+			show: {
+				internal: true,
+				external: false,
+			},
+			internal: {
+				layerIdsSelector: undefined, // implied default: layer ids of layers viewed in internal Selector
+				grouped: false,
+			},
+			external: {
+				// FIXME: function in redux state?
+				layerIdsSelector: layerIdsExternalSwitcherSelector,
+				grouped: true,
+			},
+		},
+		list: {
+			selectionBehavior: {
+				desktop: "scrollToMap", // always 'scrollToMap' for now
+				mobile: "expandInList", // either 'expandInList', 'scrollToMap', 'showInMapOnlyView'
+			},
+			detailsInList: false, // if true details will always be shown in list even if not on mobile
+			showSelectedOnly: false, // don't show list entries, only show the selected one (need some other kind of communication, cyclingControl or icons on the map)
+			highlightOnMouse: true, // highlights list item on mouse enter (and un-highlights on leave)
+			selectOnClick: true, // select on click to selected list item
+			deselectOnClick: false, // deselect on click to selected list item
+			cyclingControl: false, // show a control to select next or previous list entry
+			sortControl: true, // show sort control icon
+			filterControl: true, // show filter box
+			paginationControl: false, // show pagination
+			itemsPerPage: 10, // number of items per page
+			stickyHeader: true, // make list header sticky?
+			showVaryingListInfoOnly: true, // show info column only, if the contents vary (determined before list filter)
+		},
+		featureSelectionInfo: {
+			stickyHeader: false, // make feature selection info header sticky?
+			stuckHeaderHeight: 30, // px
+		},
+		regions: {},
+		places: {},
+	},
+
+	plugins: [],
+	renderer: defaultRenderer,
+	components: {},
+	renderBreakpoints: {
+		// NOTE: Keep in sync with css!
+		mobile: [0, 767],
+		tablet: [768, 1014],
+		desktop: [1015, -1],
+	},
+	partialChangeHandler: undefined,
+
+	// add additional reducers
+	reducers: {...uiReducers},
+};
+
+/**
+ * Creates an mapsight ui instance
+ *
+ * @param container element the mapsight ui app should be rendered into
+ * @param styleFunction the mapsight core vector style function (see @mapsight/core)
+ * @param [baseMapsightConfig] base mapsight configuration TODO: document further
+ * @param [createOptions] ui creation options TODO: document further
+ * @returns mapsight ui instance
+ */
+export function create(
+	container: HTMLElement | null,
+	styleFunction: MapsightStyleFunction,
+	baseMapsightConfig: Partial<State> = {},
+	createOptions: CreateOptions = {},
+): MapsightUiContext {
+	const context: MapsightUiContext = {
+		hasRendered: false,
+		container: container,
+		styleFunction: styleFunction,
+		baseMapsightConfig: baseMapsightConfig,
+		createOptions: merge({}, defaultCreateOptions, createOptions),
+		appChannelListeners: [],
+	};
+
+	// transfer some create options to global site config to make them available even outside of the redux context
+	// TODO: Replace this mechanic with an explicit API, e.g. exposing the site config directly as `@mapsight/ui/site-config` or
+	//    make them local to the mapsight ui context to allow for several independent instances with different site configs
+	siteConfig.baseUrl = context.createOptions.baseUrl ?? siteConfig.baseUrl;
+	siteConfig.imagesUrl =
+		context.createOptions.imagesUrl || siteConfig.imagesUrl;
+	siteConfig.searchUrl =
+		context.createOptions.searchUrl || siteConfig.searchUrl;
+	siteConfig.searchQueryParameter =
+		context.createOptions.searchQueryParameter ||
+		siteConfig.searchQueryParameter;
+
+	// initial state
+	context.initialState = merge({}, context.baseMapsightConfig, {
+		app: context.createOptions.uiState,
+	});
+	delete context.createOptions.uiState;
+
+	// override initial state by re-hydration
+	context.isStateReHydrated = false;
+	if (context.createOptions.reHydratedState !== undefined) {
+		context.isStateReHydrated = true;
+		merge(context.initialState, context.createOptions.reHydratedState);
+	}
+
+	// setup controllers
+	context.controllers = Object.assign(
+		createDefaultControllers(context),
+		context.createOptions.controllers,
+	);
+
+	// store enhancer
+	const uiStoreEnhancer = applyMiddleware(thunk);
+	context.storeEnhancer = context.createOptions.storeEnhancer
+		? compose(uiStoreEnhancer, context.createOptions.storeEnhancer)
+		: uiStoreEnhancer;
+
+	// plugin: afterInit
+	callAndForgetPlugins(context, "afterInit");
+
+	context.store = createMapsightStore<MapsightUiStore>(
+		context.controllers,
+		Object.fromEntries(
+			Object.entries(context.createOptions.reducers ?? {})
+				.map(([name, reducer]) =>
+					nonNull.map(reducer, (reducer) => [name, reducer] as const),
+				)
+				.filter(nonNull.is),
+		),
+		context.initialState,
+		context.storeEnhancer,
+	);
+
+	// render
+	function internalRender(): unknown {
+		const hydrate = !context.hasRendered && context.isStateReHydrated;
+		nonNull.assert(context.store);
+		nonNull.assert(context.createOptions.renderer);
+
+		const props: MapsightUiRendererProps = {
+			store: context.store,
+			components: context.createOptions.components || {},
+			appChannelListeners: context.appChannelListeners,
+			...context.rendererProps,
+		};
+		context.renderRef = context.createOptions.renderer(
+			context.container,
+			props,
+			hydrate,
+		);
+		context.hasRendered = true;
+
+		callAndForgetPlugins(context, "afterRender");
+
+		return context.renderRef;
+	}
+
+	// Render without waiting for plugins (for e.g. waiting on external data)
+	context.render = function mapsightUiRender(rendererProps) {
+		context.rendererProps = rendererProps;
+		context.canPluginsDelayRender = false;
+
+		callAndForgetPlugins(context, "beforeRender");
+
+		return internalRender();
+	};
+
+	// Render allowing plugins to delay render (for e.g. waiting on external data)
+	context.renderAsync = async function mapsightUiRenderAsync(rendererProps) {
+		context.rendererProps = rendererProps;
+		context.canPluginsDelayRender = true;
+
+		await callAndAwaitPlugins(context, "beforeRender");
+
+		return internalRender();
+	};
+
+	// plugin: afterCreate
+	callAndForgetPlugins(context, "afterCreate");
+
+	return context;
+}
+
+/**
+ * Overrides plugins with the same name (last to come wins), null unsets the plugin,
+ * Flattened order is in order of first occurrence of a name.
+ *
+ * @param plugins (sorted) array of plugin definitions to be flattened, null unsets
+ * @returns flattened plugin definitions
+ */
+function flattenPlugins(plugins: Array<PluginDefinition>) {
+	const pluginPositionByName: Record<string, number> = {};
+	const flattenedPlugins: Array<PluginDefinition> = [];
+
+	plugins.forEach(function filterPlugin(plugin) {
+		const [key] = plugin;
+		const position = pluginPositionByName[key];
+		if (position !== undefined) {
+			flattenedPlugins.splice(position, 1, plugin);
+		} else {
+			pluginPositionByName[key] = flattenedPlugins.length;
+			flattenedPlugins.push(plugin);
+		}
+	});
+
+	return flattenedPlugins.filter(([_, plugin]) => !!plugin);
+}
+
+/**
+ * @param context context in which the plugin will be called
+ * @param phase phase of the plugin
+ * @returns array of plugin call return values
+ */
+function callPlugins(
+	context: MapsightUiContext,
+	phase: PluginPhase,
+): Array<Promise<unknown>> {
+	return flattenPlugins(context.createOptions?.plugins ?? [])
+		.map(([_name, plugin]) => plugin?.[phase]?.(context) ?? undefined)
+		.filter(nonNull.is);
+}
+
+/**
+@param context context in which the plugin will be called
+@param phase phase of the plugin
+ */
+function callAndForgetPlugins(context: MapsightUiContext, phase: PluginPhase) {
+	Promise.allSettled(callPlugins(context, phase)).catch(() => {});
+}
+
+/**
+ * @param context context in which the plugin will be called
+ * @param phase phase of the plugin
+ * @returns promise that all plugins are resolved
+ */
+async function callAndAwaitPlugins(
+	context: MapsightUiContext,
+	phase: PluginPhase,
+): Promise<void> {
+	await Promise.all(callPlugins(context, phase));
+}

package/src/js/plugins/browser/app-title.ts

@@ -0,0 +1,36 @@
+import {setAppTitle} from "../../store/actions";
+import type {PluginInstance} from "../../types.ts";
+
+const defaultRendererPropName = "title";
+
+/**
+ * This plugin will apply a title on render passed as a prop to the renderer.
+ *
+ * @param [options] options currently not used
+ * @param [options.rendererPropName="title"] title property name passed to the renderer
+ * @returns plugin instance
+ */
+export default function createPlugin(
+	options: {
+		rendererPropName?: string;
+	} = {},
+): PluginInstance {
+	const {rendererPropName = defaultRendererPropName} = options;
+
+	return {
+		beforeRender: function appTitleRenderPlugin(context) {
+			const {store, rendererProps} = context;
+
+			if (!store || !rendererProps) {
+				return;
+			}
+
+			if (
+				rendererPropName in rendererProps &&
+				rendererProps[rendererPropName]
+			) {
+				store.dispatch(setAppTitle(rendererProps[rendererPropName]));
+			}
+		},
+	};
+}

package/src/js/plugins/browser/debug.ts

@@ -0,0 +1,37 @@
+import type {MapController} from "@mapsight/core/lib/map/controller";
+import {getIdForLayer} from "@mapsight/core/lib/map/lib/tagLayer";
+
+import type {PluginInstance} from "../../types";
+
+const defaultGlobalVariableName = "MSUI";
+
+/**
+ * This plugin will make debug info available in a global variable.
+ */
+export default function createPlugin(
+	options: {
+		globalVariableName?: string;
+	} = {},
+): PluginInstance {
+	const {globalVariableName = defaultGlobalVariableName} = options;
+
+	return {
+		afterCreate: (ctx) => {
+			// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+			// @ts-ignore
+			window[globalVariableName] = {
+				context: ctx,
+				getLayerObjects() {
+					const layerMap = {};
+					(ctx.controllers?.map as MapController)
+						.getMap()
+						?.getAllLayers()
+						.forEach((l, i) => {
+							layerMap[getIdForLayer(l) ?? "unnamed_" + i] = l;
+						});
+					return layerMap;
+				},
+			};
+		},
+	};
+}

package/src/js/plugins/browser/feature-deep-link.ts

@@ -0,0 +1,222 @@
+import type {Store} from "redux";
+
+import {
+	deselectAll,
+	selectExclusively,
+} from "@mapsight/core/lib/feature-selections/actions";
+import {createFeatureSelectionSelector} from "@mapsight/core/lib/feature-selections/selectors";
+import type {FeatureId} from "@mapsight/core/types";
+
+import getQueryStringParameter from "@mapsight/lib-js/string/get-query-string-parameter";
+import removeQueryStringParameter from "@mapsight/lib-js/string/remove-query-string-parameter";
+import {observeStateOnce} from "@mapsight/lib-redux/observe-state";
+
+import {VIEW_MAP_ONLY} from "../../config/constants/app";
+import * as c from "../../config/constants/controllers";
+import {FEATURE_SELECTION_SELECT} from "../../config/feature/selections";
+import {setView} from "../../store/actions";
+import {isViewMobile, viewSelector} from "../../store/selectors";
+import type {PluginInstance, UiState} from "../../types.ts";
+
+const defaultFeatureSelectionsController = c.FEATURE_SELECTIONS;
+const defaultFeatureSelection = FEATURE_SELECTION_SELECT;
+const defaultGetParameter = "feature";
+const defaultAutoRemoveParameters = [defaultGetParameter, "cHash"];
+
+function selectFeature(
+	store: Store,
+	featureSelectionsController: string,
+	featureSelection: string,
+	featureId: FeatureId,
+	setMapOnlyViewInMobile: boolean,
+) {
+	store.dispatch(
+		selectExclusively(
+			featureSelectionsController,
+			featureSelection,
+			featureId,
+		),
+	);
+
+	if (
+		setMapOnlyViewInMobile &&
+		isViewMobile(viewSelector(store.getState() as {app: UiState}))
+	) {
+		store.dispatch(setView(VIEW_MAP_ONLY));
+	}
+}
+
+/**
+ * Hooks into global window.history[fn] to react to
+ * history state changes from the app (as opposed to `window.onpopstate` which
+ * triggers when a browser ui actions causes a history state change).
+ *
+ * @param fn function name to patch (e.g. "pushState" or "replaceState")
+ * @param callback will get called _after_ that function has been called
+ */
+function patchWindowHistoryFunction(
+	fn: "pushState" | "replaceState",
+	callback: (state: unknown) => void,
+) {
+	const originalFn = window.history[fn];
+
+	window.history[fn] = (state, ...rest) => {
+		const returnValue: unknown = originalFn.apply(window.history, [
+			state,
+			...rest,
+		]);
+		callback(state);
+		return returnValue;
+	};
+}
+
+/**
+ * This plugin will select the feature identified by the defined get parameter and optionally remove parameters from the
+ * window.location using the history API.
+ *
+ * @param [options] options
+ * @param [options.featureSelectionsController] name of the feature selections controller, defaults to mapsight ui default
+ * @param [options.featureSelection="select"] name of the feature selection to track
+ * @param [options.getParameter="feature"] name get parameter identifying the feature
+ * @param [options.setMapOnlyViewInMobile=true] will set MapOnly view on mobile if a feature has been linked
+ * @param [options.autoRemoveParameters] list of get parameters to remove once the feature
+ *                                            has been selected, defaults to ["feature", "cHash"]. Pass false to disable.
+ * @param [options.clearMissingParameters] if set to true or an array clear if getParameter and the mentioned
+ *                                            parameters are missing. don't clear if getParameter is missing, but one of the
+ *                                            mentioned parameters is there. we keep this to be safe in race condition
+ *                                            where ?feature is set but ?preselect is not where we want to keep the implicit
+ *                                            preselect of the feature parameter
+ *
+ * @returns plugin instance
+ */
+export default function createPlugin(
+	options: {
+		featureSelectionsController?: string;
+		featureSelection?: string;
+		getParameter?: string;
+		setMapOnlyViewInMobile?: boolean;
+		autoRemoveParameters?: string[] | false;
+		clearMissingParameters?: string[] | false;
+	} = {},
+): PluginInstance {
+	const {
+		featureSelectionsController = defaultFeatureSelectionsController,
+		featureSelection = defaultFeatureSelection,
+		getParameter = defaultGetParameter,
+		autoRemoveParameters = defaultAutoRemoveParameters,
+		setMapOnlyViewInMobile = true,
+		clearMissingParameters = null,
+	} = options;
+	const selectorSelectedFeatures = createFeatureSelectionSelector(
+		featureSelectionsController,
+		featureSelection,
+	);
+
+	let isHandled = false;
+	return {
+		afterRender: function handleFeatureDeepLink(context) {
+			if (isHandled) {
+				return;
+			}
+
+			isHandled = true;
+
+			const {store} = context;
+			if (!store) {
+				return;
+			}
+
+			// We always do this action even if we should already have done that
+			// by re-hydrating the state as it may not have had the dynamic get parameter passed along
+			const featureId = getQueryStringParameter(
+				window.location.search,
+				getParameter,
+			);
+			if (featureId) {
+				selectFeature(
+					store,
+					featureSelectionsController,
+					featureSelection,
+					featureId,
+					setMapOnlyViewInMobile,
+				);
+
+				if (autoRemoveParameters && autoRemoveParameters.length) {
+					// if we can, remove initial feature id from url
+					// when the selection changes (e.g. panel is closed/different feature is selected)
+					observeStateOnce(store, selectorSelectedFeatures, () => {
+						let newUrl = window.location.href;
+						autoRemoveParameters.forEach((key) => {
+							newUrl = removeQueryStringParameter(newUrl, key);
+						});
+						window.history.pushState(
+							null,
+							window.document.title,
+							newUrl,
+						);
+					});
+				}
+			} else {
+				if (clearMissingParameters) {
+					let found: string | null = null;
+					while (!found && clearMissingParameters[0]) {
+						found = getQueryStringParameter(
+							window.location.search,
+							clearMissingParameters.shift() as string,
+						);
+					}
+					if (!found) {
+						store.dispatch(
+							deselectAll(
+								featureSelectionsController,
+								featureSelection,
+							),
+						);
+					}
+				}
+				// handle select via state at relaod
+				if (
+					window.history.state &&
+					"featureId" in window.history.state &&
+					window.history.state.featureId
+				) {
+					selectFeature(
+						store,
+						featureSelectionsController,
+						featureSelection,
+						window.history.state.featureId,
+						setMapOnlyViewInMobile,
+					);
+				}
+			}
+
+			const handleHistoryStateChange = (state) => {
+				if (state && "featureId" in state) {
+					if (state.featureId) {
+						selectFeature(
+							store,
+							featureSelectionsController,
+							featureSelection,
+							state.featureId,
+							setMapOnlyViewInMobile,
+						);
+					} else if (state?.featureId === null) {
+						// test for null to inhibit action if featureId is simply omitted
+						store.dispatch(
+							deselectAll(
+								featureSelectionsController,
+								featureSelection,
+							),
+						);
+					}
+				}
+			};
+
+			patchWindowHistoryFunction("pushState", handleHistoryStateChange);
+			patchWindowHistoryFunction(
+				"replaceState",
+				handleHistoryStateChange,
+			);
+		},
+	};
+}

package/src/js/plugins/browser/local-storage.ts

@@ -0,0 +1,79 @@
+import merge from "lodash/merge";
+
+import type {PathItem} from "@mapsight/core/lib/base/actions";
+import {mergeAll} from "@mapsight/core/lib/base/actions";
+import type {State} from "@mapsight/core/types";
+
+import pickPaths from "@mapsight/lib-js/object/pickPaths";
+import {createStorage} from "@mapsight/lib-redux/local-storage";
+
+import type {PluginInstance} from "../../types.ts";
+
+const defaultLocalStorageKey = "mapsight--v3-ui";
+const defaultLocalStoragePaths = [
+	//['app', 'isFullscreen'],
+	//['app', 'view'],
+	["app", "userPreferenceListVisible"],
+];
+
+/**
+ * This plugin will synchronize some paths of the store with the browser's local storage and restored on initialization.
+ * See {CreateOptions.localStorageKey} and {CreateOptions.localStoragePaths} for configuration.
+ *
+ * @param [options] options
+ * @param [options.localStorageKey="mapsight--v3-ui"] storage key
+ * @param [options.localStoragePaths] paths to store
+ * @returns plugin instance
+ */
+export default function createPlugin({
+	localStorageKey = defaultLocalStorageKey,
+	localStoragePaths = defaultLocalStoragePaths,
+} = {}): PluginInstance {
+	if (typeof window === "undefined") {
+		console.error("This plugin will only work as intended in the browser!");
+	}
+
+	let restoredState: Partial<State>;
+	let isRestored = false;
+	let storage: ReturnType<typeof createStorage>;
+
+	return {
+		afterInit: function localStorageInitPlugin({
+			initialState,
+			isStateReHydrated,
+		}) {
+			storage = createStorage(localStorageKey);
+
+			// override initial state from local storage
+			const savedState = storage.getLocalStorageState();
+			restoredState = pickPaths(savedState, localStoragePaths);
+
+			// We cannot change the state before we have not at least rendered the
+			// dehydrated html at least once to prevent a mixed up DOM when server-side
+			// state and client-side determined state mismatch or has changed
+			// since page load. If the app is not re-hydrated but initially rendered
+			// in the client we can omit the additional render and set the restored
+			// state on creation (before render).
+			if (!isStateReHydrated) {
+				isRestored = true;
+				merge(initialState, restoredState);
+			}
+		},
+		afterCreate: function localStorageCreatePlugin({store}) {
+			// sync local storage
+			if (store && localStoragePaths) {
+				storage.synchronizePathsToLocalStorage(
+					store,
+					localStoragePaths,
+				);
+			}
+		},
+		afterRender: function localStorageAfterRenderPlugin({store}) {
+			if (store && !isRestored) {
+				store.dispatch(
+					mergeAll(restoredState as Record<PathItem, unknown>),
+				);
+			}
+		},
+	};
+}