@schukai/monster 4.142.3 → 4.143.0

package/package.json

@@ -1 +1 @@
-{"author":"Volker Schukai","dependencies":{"@floating-ui/dom":"^1.7.6"},"description":"Monster is a simple library for creating fast, robust and lightweight websites.","homepage":"https://monsterjs.org/","keywords":["framework","web","dom","css","sass","mobile-first","app","front-end","templates","schukai","core","shopcloud","alvine","monster","buildmap","stack","observer","observable","uuid","node","nodelist","css-in-js","logger","log","theme"],"license":"AGPL 3.0","main":"source/monster.mjs","module":"source/monster.mjs","name":"@schukai/monster","repository":{"type":"git","url":"https://gitlab.schukai.com/oss/libraries/javascript/monster.git"},"type":"module","version":"4.142.3"}
+{"author":"Volker Schukai","dependencies":{"@floating-ui/dom":"^1.7.6"},"description":"Monster is a simple library for creating fast, robust and lightweight websites.","homepage":"https://monsterjs.org/","keywords":["framework","web","dom","css","sass","mobile-first","app","front-end","templates","schukai","core","shopcloud","alvine","monster","buildmap","stack","observer","observable","uuid","node","nodelist","css-in-js","logger","log","theme"],"license":"AGPL 3.0","main":"source/monster.mjs","module":"source/monster.mjs","name":"@schukai/monster","repository":{"type":"git","url":"https://gitlab.schukai.com/oss/libraries/javascript/monster.git"},"type":"module","version":"4.143.0"}

package/source/components/datatable/datatable.mjs

@@ -76,7 +76,7 @@ import {
 import { getDocumentTranslations } from "../../i18n/translations.mjs";
 import "../state/state.mjs";
 import "../host/collapse.mjs";
-import { generateUniqueConfigKey } from "../host/util.mjs";
+import { generateComponentConfigKey } from "../host/util.mjs";
 
 import "./datasource/dom.mjs";
 import "./datasource/rest.mjs";
@@ -279,6 +279,10 @@ class DataTable extends CustomElement {
 					"row-key": null,
 					"filter-id": null,
 				},
+
+				config: {
+					instanceKey: null,
+				},
 			},
 			initOptionsFromArguments.call(this),
 		);
@@ -659,15 +663,21 @@ class DataTable extends CustomElement {
  * @return {string}
  */
 function getColumnVisibilityConfigKey() {
-	return generateUniqueConfigKey("datatable", this?.id, "columns-visibility");
+	return generateComponentConfigKey("datatable", this?.id, "columns-visibility", {
+		instanceKey: this.getOption("config.instanceKey"),
+	});
 }
 
 /**
  * @private
  * @return {string}
  */
-function getFilterConfigKey() {
-	return generateUniqueConfigKey("datatable", this?.id, "filter");
+function hasConfigIdentity() {
+	return (
+		(isString(this.id) && this.id !== "") ||
+		(isString(this.getOption("config.instanceKey")) &&
+			this.getOption("config.instanceKey").trim() !== "")
+	);
 }
 
 /**
@@ -682,8 +692,11 @@ function getHostConfig(callback) {
 		return Promise.resolve({});
 	}
 
-	if (!this.id) {
-		addErrorAttribute(this, "no id found; id is required for config");
+	if (!hasConfigIdentity.call(this)) {
+		addErrorAttribute(
+			this,
+			"no id or config.instanceKey found; one is required for config",
+		);
 		return Promise.resolve({});
 	}
 
@@ -782,7 +795,7 @@ function updateConfigColumnBar() {
 	}
 
 	const host = findElementWithSelectorUpwards(this, "monster-host");
-	if (!(host && this.id)) {
+	if (!(host && hasConfigIdentity.call(this))) {
 		return;
 	}
 	const configKey = getColumnVisibilityConfigKey.call(this);
@@ -1616,7 +1629,9 @@ function getTranslations() {
  * @return {string}
  */
 export function getStoredOrderConfigKey() {
-	return generateUniqueConfigKey("datatable", this?.id, "stored-order");
+	return generateComponentConfigKey("datatable", this?.id, "stored-order", {
+		instanceKey: this.getOption("config.instanceKey"),
+	});
 }
 
 /**
@@ -1629,7 +1644,7 @@ function storeOrderStatement(doFetch) {
 	setDataSource.call(this, { order: statement }, doFetch);
 
 	const host = findElementWithSelectorUpwards(this, "monster-host");
-	if (!(host && this.id)) {
+	if (!(host && hasConfigIdentity.call(this))) {
 		return;
 	}
 

package/source/components/datatable/filter/util.mjs

@@ -12,14 +12,16 @@
  * SPDX-License-Identifier: AGPL-3.0
  */
 
-import { generateUniqueConfigKey } from "../../host/util.mjs";
+import { generateComponentConfigKey } from "../../host/util.mjs";
 
 /**
  * @private
  * @return {string}
  */
 export function getFilterConfigKey() {
-	return generateUniqueConfigKey("datatable", this?.id, "filter");
+	return generateComponentConfigKey("datatable", this?.id, "filter", {
+		instanceKey: this.getOption("config.instanceKey"),
+	});
 }
 
 /**
@@ -27,7 +29,9 @@ export function getFilterConfigKey() {
  * @return {string}
  */
 export function getStoredFilterConfigKey() {
-	return generateUniqueConfigKey("datatable", this?.id, "stored-filter");
+	return generateComponentConfigKey("datatable", this?.id, "stored-filter", {
+		instanceKey: this.getOption("config.instanceKey"),
+	});
 }
 
 /**

package/source/components/datatable/filter.mjs

@@ -293,6 +293,10 @@ class Filter extends CustomElement {
 				selector: "",
 			},
 
+			config: {
+				instanceKey: null,
+			},
+
 			timeouts: {
 				message: 4000,
 			},
@@ -915,7 +919,7 @@ function initEventHandler() {
 					.then(() => {
 						const configKey = getStoredFilterConfigKey.call(self);
 						const host = getDocument().querySelector("monster-host");
-						if (!host) {
+						if (!(host && hasConfigIdentity.call(self))) {
 							return;
 						}
 
@@ -1070,7 +1074,7 @@ function initTabEvents() {
 			}
 
 			const host = findElementWithSelectorUpwards(this, "monster-host");
-			if (!(host && this.id)) {
+			if (!(host && hasConfigIdentity.call(this))) {
 				return;
 			}
 
@@ -1111,7 +1115,7 @@ function updateFilterTabs() {
 	}
 
 	const host = findElementWithSelectorUpwards(this, "monster-host");
-	if (!(host && this.id)) {
+	if (!(host && hasConfigIdentity.call(this))) {
 		return;
 	}
 
@@ -1580,7 +1584,7 @@ function getControlValuesFromLabel(label) {
 function initFromConfig() {
 	const host = findElementWithSelectorUpwards(this, "monster-host");
 
-	if (!(isInstance(host, Host) && this.id)) {
+	if (!(isInstance(host, Host) && hasConfigIdentity.call(this))) {
 		return Promise.resolve();
 	}
 
@@ -1622,7 +1626,7 @@ function initFromConfig() {
  */
 function updateConfig() {
 	const host = findElementWithSelectorUpwards(this, "monster-host");
-	if (!(host && this.id)) {
+	if (!(host && hasConfigIdentity.call(this))) {
 		return;
 	}
 	const configKey = getFilterConfigKey.call(this);
@@ -1634,6 +1638,18 @@ function updateConfig() {
 	}
 }
 
+/**
+ * @private
+ * @return {boolean}
+ */
+function hasConfigIdentity() {
+	return (
+		(isString(this.id) && this.id !== "") ||
+		(isString(this.getOption("config.instanceKey")) &&
+			this.getOption("config.instanceKey").trim() !== "")
+	);
+}
+
 /**
  * @private
  * @return {string}

package/source/components/form/select.mjs

@@ -2088,6 +2088,12 @@ function fetchIt(url, controlOptions) {
 
 						queueMicrotask(() => {
 							checkOptionState.call(this);
+							if (
+								getFilterMode.call(this) === FILTER_MODE_REMOTE &&
+								this.getOption("options", []).length === 0
+							) {
+								calcAndSetOptionsDimension.call(this);
+							}
 							setTotalText.call(this);
 							updatePopper.call(this);
 							setStatusOrRemoveBadges.call(this, "closed");
@@ -2509,14 +2515,22 @@ function scheduleSelectLayoutCycle(
 }
 
 function hasConfiguredOptionsWaitingForRender() {
+	if (getFilterMode.call(this) === FILTER_MODE_REMOTE) {
+		return false;
+	}
+
 	const options = this.getOption("options");
 
 	if (isArray(options)) {
-		return options.length > 0;
+		if (options.length > 0) {
+			return true;
+		}
+
+		return getSlottedElements.call(this, "div").length > 0;
 	}
 
 	if (!isIterable(options) || isString(options)) {
-		return false;
+		return getSlottedElements.call(this, "div").length > 0;
 	}
 
 	for (const option of options) {
@@ -2546,7 +2560,9 @@ function retryPendingOpenIntent() {
 	}
 
 	if (getOptionElements.call(this).length === 0) {
-		clearPendingOpenIntent.call(this);
+		if (!hasConfiguredOptionsWaitingForRender.call(this)) {
+			clearPendingOpenIntent.call(this);
+		}
 		return;
 	}
 
@@ -3658,6 +3674,8 @@ function getSelectPopperPositionOptions() {
 		popperOptions.placement = getDefaultSelectPopperPositionProfile().placement;
 	}
 
+	popperOptions.adaptiveSize = false;
+
 	if (
 		resolveParentPopperContentBoundary(
 			this[controlElementSymbol],
@@ -4969,6 +4987,8 @@ function show() {
 	const options = getOptionElements.call(this);
 	if (options.length === 0 && hasPopperFilterFlag === false) {
 		if (hasConfiguredOptionsWaitingForRender.call(this)) {
+			removeErrorAttribute(this, "No options available.");
+			setStatusOrRemoveBadges.call(this, "loading");
 			queuePendingOpenIntent.call(this);
 		}
 		return;

package/source/components/form/util/floating-layout-queue.mjs

@@ -27,6 +27,12 @@ const jobs = new Map();
 let queueFrame = null;
 let queueTimeout = null;
 let flushing = false;
+const OSCILLATION_HISTORY_LIMIT = 4;
+const OSCILLATION_TIME_WINDOW_MS = 1000;
+const OSCILLATION_SAFE_REASONS =
+	FLOATING_LAYOUT_REASON.POSITION |
+	FLOATING_LAYOUT_REASON.RESIZE |
+	FLOATING_LAYOUT_REASON.SETTLE;
 
 function enqueueFloatingLayout({
 	popperElement,
@@ -105,6 +111,7 @@ function createJob(popperElement) {
 		running: false,
 		pending: false,
 		cancelled: false,
+		layoutSignatures: [],
 		promise,
 		resolve,
 	};
@@ -220,9 +227,67 @@ async function flushJob(job) {
 		}
 	} finally {
 		job.running = false;
+		recordLayoutSignature(job);
+		if (job.pending && shouldSuppressOscillatingPendingLayout(job)) {
+			job.pending = false;
+			job.reasons = 0;
+		}
 		if (!job.pending && job.reasons === 0) {
 			job.resolve();
 			jobs.delete(job.popperElement);
 		}
 	}
 }
+
+function recordLayoutSignature(job) {
+	if (!(job?.popperElement instanceof HTMLElement)) {
+		return;
+	}
+
+	const rect = job.popperElement.getBoundingClientRect();
+	const signature = [
+		Math.round(rect.x),
+		Math.round(rect.y),
+		Math.round(rect.width),
+		Math.round(rect.height),
+	].join("/");
+
+	job.layoutSignatures.push({
+		signature,
+		time: performanceNow(),
+	});
+	if (job.layoutSignatures.length > OSCILLATION_HISTORY_LIMIT) {
+		job.layoutSignatures.shift();
+	}
+}
+
+function shouldSuppressOscillatingPendingLayout(job) {
+	if ((job.reasons & ~OSCILLATION_SAFE_REASONS) !== 0) {
+		return false;
+	}
+
+	const signatures = job.layoutSignatures;
+	if (signatures.length < OSCILLATION_HISTORY_LIMIT) {
+		return false;
+	}
+
+	const [a, b, c, d] = signatures;
+	if (d.time - a.time > OSCILLATION_TIME_WINDOW_MS) {
+		return false;
+	}
+
+	return (
+		a.signature === c.signature &&
+		b.signature === d.signature &&
+		a.signature !== b.signature
+	);
+}
+
+function performanceNow() {
+	const globalObject = getGlobal();
+	if (globalObject?.performance?.now instanceof Function) {
+		return globalObject.performance.now();
+	}
+
+	return Date.now();
+}

package/source/components/form/util/floating-ui.mjs

@@ -132,9 +132,12 @@ function syncFloatingPopover(
 		config.detectOverflowOptions,
 		popperElement,
 		syncCycleId,
+		config.adaptiveSize,
 	);
 
-	resetAdaptiveFloatingElementSize(popperElement);
+	if (config.adaptiveSize !== false) {
+		resetAdaptiveFloatingElementSize(popperElement);
+	}
 
 	if (
 		arrowElement instanceof HTMLElement &&
@@ -143,7 +146,10 @@ function syncFloatingPopover(
 		floatingMiddleware.push(arrow({ element: arrowElement }));
 	}
 
-	if (!config.middlewareTokens.includes("size")) {
+	if (
+		config.adaptiveSize !== false &&
+		!config.middlewareTokens.includes("size")
+	) {
 		floatingMiddleware.push(
 			createAdaptiveSizeMiddleware(
 				config.detectOverflowOptions,
@@ -206,6 +212,7 @@ function normalizePopperConfig(options, controlElement, popperElement) {
 			placement: "top",
 			engine: "floating",
 			strategy: "absolute",
+			adaptiveSize: true,
 		},
 		options,
 	);
@@ -247,6 +254,7 @@ function buildFloatingMiddleware(
 	detectOverflowOptions,
 	popperElement,
 	syncCycleId = null,
+	adaptiveSize = true,
 ) {
 	const result = [...middleware];
 
@@ -272,7 +280,7 @@ function buildFloatingMiddleware(
 			case "shift":
 				result[key] = shift(normalizeShiftOptions(kv, detectOverflowOptions));
 				break;
-			case "autoPlacement":
+			case "autoPlacement": {
 				let defaultAllowedPlacements = ["top", "bottom", "left", "right"];
 
 				const defPlacement = kv?.shift();
@@ -298,18 +306,22 @@ function buildFloatingMiddleware(
 					}),
 				);
 				break;
+			}
 			case "arrow":
 				result[key] = null;
 				break;
 			case "size":
-				result[key] = createAdaptiveSizeMiddleware(
-					detectOverflowOptions,
-					popperElement,
-					syncCycleId,
-				);
+				result[key] =
+					adaptiveSize === false
+						? null
+						: createAdaptiveSizeMiddleware(
+								detectOverflowOptions,
+								popperElement,
+								syncCycleId,
+							);
 				break;
 			case "offset":
-				result[key] = offset(parseInt(kv?.shift()) || 10);
+				result[key] = offset(parseInt(kv?.shift(), 10) || 10);
 				break;
 			case "hide":
 				result[key] = hide(detectOverflowOptions);

package/source/components/host/config-manager.mjs

@@ -21,6 +21,7 @@ import { ConfigManagerStyleSheet } from "./stylesheet/config-manager.mjs";
 import { getWindow } from "../../dom/util.mjs";
 import { instanceSymbol } from "../../constants.mjs";
 import { diff } from "../../data/diff.mjs";
+import { isFunction, isObject } from "../../types/is.mjs";
 
 export { ConfigManager };
 
@@ -108,17 +109,42 @@ class ConfigManager extends CustomElement {
 					keyPath: "key",
 				},
 			},
+			storage: {
+				adapter: null,
+				serverAuthoritative: false,
+			},
 		});
 	}
 
+	/**
+	 * Register an external host configuration storage adapter.
+	 *
+	 * Supported adapter methods are getConfig/hasConfig/setConfig/deleteConfig
+	 * or their short aliases get/has/set/delete. If managesConfigKey, managesKey
+	 * or manages is present, it is used to decide whether a key is handled by
+	 * the adapter. Without such a method, an adapter handles all keys.
+	 *
+	 * @param {Object|null} adapter
+	 * @return {ConfigManager}
+	 */
+	setStorageAdapter(adapter) {
+		this.setOption("storage.adapter", adapter);
+		return this;
+	}
+
+	/**
+	 * @return {Object|null}
+	 */
+	getStorageAdapter() {
+		return getStorageAdapter.call(this);
+	}
+
 	/**
 	 * @param {string} key
 	 * @return {Promise<unknown>}
 	 */
 	getConfig(key) {
-		return this.ready().then(() => {
-			return getBlob.call(this, key);
-		});
+		return this.ready().then(() => readConfig.call(this, key));
 	}
 
 	/**
@@ -126,16 +152,7 @@ class ConfigManager extends CustomElement {
 	 * @return {Promise<boolean>}
 	 */
 	hasConfig(key) {
-		return this.ready()
-			.then(() => {
-				return getBlob.call(this, key);
-			})
-			.then(() => {
-				return true;
-			})
-			.catch(() => {
-				return false;
-			});
+		return this.ready().then(() => hasConfig.call(this, key));
 	}
 
 	/**
@@ -144,28 +161,11 @@ class ConfigManager extends CustomElement {
 	 * @return {Promise<unknown>}
 	 */
 	setConfig(key, value) {
-		return this.ready().then(() => {
-			return getBlob
-				.call(this, key)
-				.then((storedValue) => {
-					if (diff(storedValue, value).length === 0) {
-						return;
-					}
-					return setBlob.call(this, key, value);
-				})
-				.catch((error) => {
-					if (error?.message?.match(/is not defined/)) {
-						return setBlob.call(this, key, value);
-					}
-					throw error;
-				});
-		});
+		return this.ready().then(() => writeConfig.call(this, key, value));
 	}
 
 	deleteConfig(key) {
-		return this.ready().then(() => {
-			return deleteBlob.call(this, key);
-		});
+		return this.ready().then(() => removeConfig.call(this, key));
 	}
 
 	/**
@@ -190,6 +190,192 @@ class ConfigManager extends CustomElement {
 	}
 }
 
+/**
+ * @private
+ * @return {Object|null}
+ */
+function getStorageAdapter() {
+	const adapter = this.getOption("storage.adapter");
+	return isObject(adapter) ? adapter : null;
+}
+
+/**
+ * @private
+ * @param {Object} adapter
+ * @param {string} key
+ * @return {boolean}
+ */
+function adapterManagesKey(adapter, key) {
+	for (const methodName of ["managesConfigKey", "managesKey", "manages"]) {
+		if (isFunction(adapter?.[methodName])) {
+			return adapter[methodName](key) === true;
+		}
+	}
+
+	return true;
+}
+
+/**
+ * @private
+ * @param {Object} adapter
+ * @param {string[]} methodNames
+ * @param {Array} args
+ * @return {Promise<unknown>}
+ */
+function callAdapter(adapter, methodNames, args) {
+	for (const methodName of methodNames) {
+		if (isFunction(adapter?.[methodName])) {
+			return Promise.resolve(adapter[methodName](...args));
+		}
+	}
+
+	return Promise.reject(new Error("The storage adapter method is not defined."));
+}
+
+/**
+ * @private
+ * @return {boolean}
+ */
+function isServerAuthoritative() {
+	return this.getOption("storage.serverAuthoritative") === true;
+}
+
+/**
+ * @private
+ * @param {string} key
+ * @return {Promise<unknown>}
+ */
+function readConfig(key) {
+	const adapter = getStorageAdapter.call(this);
+	const managed = adapter && adapterManagesKey(adapter, key);
+
+	if (managed) {
+		return callAdapter(adapter, ["getConfig", "get"], [key]).catch((error) => {
+			if (isServerAuthoritative.call(this)) {
+				throw error;
+			}
+			return getBlob.call(this, key);
+		});
+	}
+
+	return getBlob.call(this, key);
+}
+
+/**
+ * @private
+ * @param {string} key
+ * @return {Promise<boolean>}
+ */
+function hasConfig(key) {
+	const adapter = getStorageAdapter.call(this);
+	const managed = adapter && adapterManagesKey(adapter, key);
+
+	if (managed) {
+		return callAdapter(adapter, ["hasConfig", "has"], [key])
+			.catch(() => {
+				return callAdapter(adapter, ["getConfig", "get"], [key]).then(
+					() => true,
+				);
+			})
+			.then((result) => {
+				if (result === true || isServerAuthoritative.call(this)) {
+					return result === true;
+				}
+				return hasLocalConfig.call(this, key);
+			})
+			.catch(() => {
+				if (isServerAuthoritative.call(this)) {
+					return false;
+				}
+				return hasLocalConfig.call(this, key);
+			});
+	}
+
+	return hasLocalConfig.call(this, key);
+}
+
+/**
+ * @private
+ * @param {string} key
+ * @return {Promise<boolean>}
+ */
+function hasLocalConfig(key) {
+	return getBlob
+		.call(this, key)
+		.then(() => true)
+		.catch(() => false);
+}
+
+/**
+ * @private
+ * @param {string} key
+ * @param {*} value
+ * @return {Promise<unknown>}
+ */
+function writeConfig(key, value) {
+	const adapter = getStorageAdapter.call(this);
+	const managed = adapter && adapterManagesKey(adapter, key);
+
+	if (managed) {
+		return callAdapter(adapter, ["setConfig", "set"], [key, value]).catch(
+			(error) => {
+				if (isServerAuthoritative.call(this)) {
+					throw error;
+				}
+				return writeLocalConfig.call(this, key, value);
+			},
+		);
+	}
+
+	return writeLocalConfig.call(this, key, value);
+}
+
+/**
+ * @private
+ * @param {string} key
+ * @param {*} value
+ * @return {Promise<unknown>}
+ */
+function writeLocalConfig(key, value) {
+	return getBlob
+		.call(this, key)
+		.then((storedValue) => {
+			if (diff(storedValue, value).length === 0) {
+				return;
+			}
+			return setBlob.call(this, key, value);
+		})
+		.catch((error) => {
+			if (error?.message?.match(/is not defined/)) {
+				return setBlob.call(this, key, value);
+			}
+			throw error;
+		});
+}
+
+/**
+ * @private
+ * @param {string} key
+ * @return {Promise<unknown>}
+ */
+function removeConfig(key) {
+	const adapter = getStorageAdapter.call(this);
+	const managed = adapter && adapterManagesKey(adapter, key);
+
+	if (managed) {
+		return callAdapter(adapter, ["deleteConfig", "delete", "remove"], [
+			key,
+		]).catch((error) => {
+			if (isServerAuthoritative.call(this)) {
+				throw error;
+			}
+			return deleteBlob.call(this, key);
+		});
+	}
+
+	return deleteBlob.call(this, key);
+}
+
 /**
  * @private
  * @returns {Promise<unknown>}
@@ -206,6 +392,10 @@ function openDatabase() {
 		throw new Error("The database name and version must be set.");
 	}
 
+	if (!window.indexedDB) {
+		return Promise.resolve(null);
+	}
+
 	const request = window.indexedDB.open(name, version);
 
 	return new Promise((resolve, reject) => {

package/source/components/host/host.mjs

@@ -194,6 +194,32 @@ class Host extends CustomElement {
 		return this[configManagerElementSymbol].setConfig(key, value);
 	}
 
+	/**
+	 * Register an external storage adapter for host configuration.
+	 *
+	 * @param {Object|null} adapter
+	 * @return {Host}
+	 */
+	setConfigStorageAdapter(adapter) {
+		if (this[configManagerElementSymbol] instanceof HTMLElement === false) {
+			throw new Error("There is no config manager element");
+		}
+
+		this[configManagerElementSymbol].setStorageAdapter(adapter);
+		return this;
+	}
+
+	/**
+	 * @return {Object|null}
+	 */
+	getConfigStorageAdapter() {
+		if (this[configManagerElementSymbol] instanceof HTMLElement === false) {
+			throw new Error("There is no config manager element");
+		}
+
+		return this[configManagerElementSymbol].getStorageAdapter();
+	}
+
 	/**
 	 * @private
 	 * @fires Host#monster-host-connected

package/source/components/host/util.mjs

@@ -13,8 +13,14 @@
  */
 
 import { getWindow } from "../../dom/util.mjs";
+import { isString } from "../../types/is.mjs";
 
-export { generateUniqueConfigKey };
+export {
+	generateConfigKey,
+	generateComponentConfigKey,
+	generateUniqueConfigKey,
+	sanitizeConfigKey,
+};
 
 /**
  * Generate a unique configuration key based on the current browser location,
@@ -38,5 +44,49 @@ function generateUniqueConfigKey(componentName, id, prefix) {
 	const uniqueKey = `${prefix}_${urlWithoutParamsAndHash}_${componentName}_${id}`;
 
 	// Replace any special characters and spaces with underscores
-	return uniqueKey.replace(/[^\w\s]/gi, "_").replace(/\s+/g, "_");
+	return sanitizeConfigKey(uniqueKey);
+}
+
+/**
+ * Generate a stable host configuration key from an explicit technical instance key.
+ *
+ * @param {string} componentName - The name of the component.
+ * @param {string} instanceKey - Technical, host-defined instance key.
+ * @param {string} scope - Configuration scope, for example "filter".
+ * @return {string}
+ */
+function generateConfigKey(componentName, instanceKey, scope) {
+	return sanitizeConfigKey(`${scope}_${componentName}_${instanceKey}`);
+}
+
+/**
+ * Generate a component host configuration key.
+ *
+ * If an explicit instance key is provided, the key is independent from the
+ * current URL and DOM id. Without an instance key, this keeps the historical
+ * URL-derived key for backwards compatibility.
+ *
+ * @param {string} componentName
+ * @param {string} id
+ * @param {string} scope
+ * @param {object} [options]
+ * @param {string} [options.instanceKey]
+ * @return {string}
+ */
+function generateComponentConfigKey(componentName, id, scope, options = {}) {
+	if (isString(options.instanceKey) && options.instanceKey.trim() !== "") {
+		return generateConfigKey(componentName, options.instanceKey.trim(), scope);
+	}
+
+	return generateUniqueConfigKey(componentName, id, scope);
+}
+
+/**
+ * @param {string} key
+ * @return {string}
+ */
+function sanitizeConfigKey(key) {
+	return String(key)
+		.replace(/[^\w\s]/gi, "_")
+		.replace(/\s+/g, "_");
 }

package/test/cases/components/datatable/config-keys.mjs

@@ -0,0 +1,47 @@
+import { expect } from "chai";
+import { initJSDOM } from "../../../util/jsdom.mjs";
+
+let getStoredOrderConfigKey;
+let getFilterConfigKey;
+let getStoredFilterConfigKey;
+
+describe("Datatable config keys", function () {
+	before(function (done) {
+		initJSDOM().then(() => {
+			import("../../../../source/components/datatable/datatable.mjs")
+				.then((m) => {
+					getStoredOrderConfigKey = m.getStoredOrderConfigKey;
+					return import(
+						"../../../../source/components/datatable/filter/util.mjs"
+					);
+				})
+				.then((m) => {
+					getFilterConfigKey = m.getFilterConfigKey;
+					getStoredFilterConfigKey = m.getStoredFilterConfigKey;
+					done();
+				})
+				.catch(done);
+		});
+	});
+
+	it("uses the same explicit instance-key contract for filter, stored filters and sorting", function () {
+		const context = {
+			id: "dom-id",
+			getOption(path) {
+				if (path === "config.instanceKey") {
+					return "orders.default";
+				}
+			},
+		};
+
+		expect(getFilterConfigKey.call(context)).to.equal(
+			"filter_datatable_orders_default",
+		);
+		expect(getStoredFilterConfigKey.call(context)).to.equal(
+			"stored_filter_datatable_orders_default",
+		);
+		expect(getStoredOrderConfigKey.call(context)).to.equal(
+			"stored_order_datatable_orders_default",
+		);
+	});
+});

package/test/cases/components/host/config-manager.mjs

@@ -0,0 +1,86 @@
+import * as chai from "chai";
+import { initJSDOM } from "../../../util/jsdom.mjs";
+
+const expect = chai.expect;
+
+describe("ConfigManager storage adapter", function () {
+	before(function (done) {
+		initJSDOM().then(() => {
+			import("../../../../source/components/host/config-manager.mjs")
+				.then(() => {
+					done();
+				})
+				.catch((e) => done(e));
+		});
+	});
+
+	afterEach(() => {
+		let mocks = document.getElementById("mocks");
+		mocks.innerHTML = "";
+	});
+
+	it("uses an external storage adapter for managed keys", function (done) {
+		const config = document.createElement("monster-config-manager");
+		const values = new Map();
+		const calls = [];
+
+		config.setStorageAdapter({
+			managesConfigKey: (key) => key.startsWith("server_"),
+			hasConfig: (key) => values.has(key),
+			getConfig: (key) => values.get(key),
+			setConfig: (key, value) => {
+				calls.push(["set", key, value]);
+				values.set(key, value);
+			},
+			deleteConfig: (key) => {
+				calls.push(["delete", key]);
+				values.delete(key);
+			},
+		});
+
+		config.setOption("storage.serverAuthoritative", true);
+
+		config
+			.setConfig("server_table_filter", { visible: true })
+			.then(() => config.hasConfig("server_table_filter"))
+			.then((hasConfig) => {
+				expect(hasConfig).to.equal(true);
+				return config.getConfig("server_table_filter");
+			})
+			.then((value) => {
+				expect(value).to.deep.equal({ visible: true });
+				expect(calls).to.deep.equal([
+					["set", "server_table_filter", { visible: true }],
+				]);
+				return config.deleteConfig("server_table_filter");
+			})
+			.then(() => {
+				expect(values.has("server_table_filter")).to.equal(false);
+				done();
+			})
+			.catch(done);
+	});
+
+	it("does not fall back to IndexedDB for server-authoritative adapter keys", function (done) {
+		const config = document.createElement("monster-config-manager");
+
+		config.setStorageAdapter({
+			managesConfigKey: (key) => key === "server_key",
+			setConfig: () => Promise.reject(new Error("server unavailable")),
+		});
+		config.setOption("storage.serverAuthoritative", true);
+		config.setOption("indexDB.objectStore.name", "missing-store");
+
+		config
+			.setConfig("server_key", { value: 1 })
+			.then(() => done(new Error("setConfig should reject")))
+			.catch((error) => {
+				try {
+					expect(error.message).to.equal("server unavailable");
+					done();
+				} catch (e) {
+					done(e);
+				}
+			});
+	});
+});

package/test/cases/components/host/util.mjs

@@ -1,79 +1,105 @@
 // Import the required libraries
-import { expect } from 'chai';
+import { expect } from "chai";
 //import { JSDOM } from 'jsdom';
-import { generateUniqueConfigKey } from '../../../../source/components/host/util.mjs';
-import {initJSDOM} from "../../../util/jsdom.mjs";
+import {
+	generateComponentConfigKey,
+	generateConfigKey,
+	generateUniqueConfigKey,
+} from "../../../../source/components/host/util.mjs";
+import { initJSDOM } from "../../../util/jsdom.mjs";
 
 // Create a JSDOM instance to simulate the browser environment
 //const dom = new JSDOM();
 
-
 // Test suite for the generateUniqueConfigKey function
-describe('generateUniqueConfigKey', () => {
-
-    //let originalWindow;
-
-    // before(() => {
-    //     // Store the original window object
-    //     originalWindow = globalThis.window;
-    //
-    //     // Create a JSDOM instance to simulate the browser environment
-    //     const dom = new JSDOM();
-    //     globalThis.window = dom.window;
-    // });
-
-
-    before(function (done) {
-        initJSDOM().then(() => {
-            done();
-        });
-    })    
-
-    // ... (same test cases as before)
-
-    after(() => {
-        // Restore the original window object
-       // globalThis.window = originalWindow;
-    });    
-    
-    it('should generate a unique key with the given parameters', () => {
-        const componentName = 'MyComponent';
-        const id = '123';
-        const prefix = 'myPrefix';
-
-        const uniqueKey = generateUniqueConfigKey(componentName, id, prefix);
-
-        // Ensure the unique key contains the given parameters and follows the expected format
-        expect(uniqueKey).to.include(prefix);
-        expect(uniqueKey).to.include(componentName);
-        expect(uniqueKey).to.include(id);
-        expect(uniqueKey).to.match(/^[a-zA-Z0-9_]+$/);
-    });
-
-    it('should replace special characters and spaces with underscores', () => {
-        const componentName = 'My$Component';
-        const id = '12#3';
-        const prefix = 'my Prefix';
-
-        const uniqueKey = generateUniqueConfigKey(componentName, id, prefix);
-
-        // Ensure the unique key does not contain any special characters or spaces
-        expect(uniqueKey).to.match(/^[a-zA-Z0-9_]+$/);
-    });
-
-    it('should include the browser location without parameters', () => {
-        const componentName = 'MyComponent';
-        const id = '123';
-        const prefix = 'myPrefix';
-
-        const uniqueKey = generateUniqueConfigKey(componentName, id, prefix);
-
-        // Ensure the unique key contains the browser location without parameters
-        const urlWithoutParams = window.location.href.split('?')[0];
-        const sanitizedUrl = urlWithoutParams.replace(/[^\w\s]/gi, '_').replace(/\s+/g, '_');
-        expect(uniqueKey).to.include(sanitizedUrl);
-    });
-
-    
-    
-})
+describe("generateUniqueConfigKey", () => {
+	//let originalWindow;
+
+	// before(() => {
+	//     // Store the original window object
+	//     originalWindow = globalThis.window;
+	//
+	//     // Create a JSDOM instance to simulate the browser environment
+	//     const dom = new JSDOM();
+	//     globalThis.window = dom.window;
+	// });
+
+	before(function (done) {
+		initJSDOM().then(() => {
+			done();
+		});
+	});
+
+	// ... (same test cases as before)
+
+	after(() => {
+		// Restore the original window object
+		// globalThis.window = originalWindow;
+	});
+
+	it("should generate a unique key with the given parameters", () => {
+		const componentName = "MyComponent";
+		const id = "123";
+		const prefix = "myPrefix";
+
+		const uniqueKey = generateUniqueConfigKey(componentName, id, prefix);
+
+		// Ensure the unique key contains the given parameters and follows the expected format
+		expect(uniqueKey).to.include(prefix);
+		expect(uniqueKey).to.include(componentName);
+		expect(uniqueKey).to.include(id);
+		expect(uniqueKey).to.match(/^[a-zA-Z0-9_]+$/);
+	});
+
+	it("should replace special characters and spaces with underscores", () => {
+		const componentName = "My$Component";
+		const id = "12#3";
+		const prefix = "my Prefix";
+
+		const uniqueKey = generateUniqueConfigKey(componentName, id, prefix);
+
+		// Ensure the unique key does not contain any special characters or spaces
+		expect(uniqueKey).to.match(/^[a-zA-Z0-9_]+$/);
+	});
+
+	it("should include the browser location without parameters", () => {
+		const componentName = "MyComponent";
+		const id = "123";
+		const prefix = "myPrefix";
+
+		const uniqueKey = generateUniqueConfigKey(componentName, id, prefix);
+
+		// Ensure the unique key contains the browser location without parameters
+		const urlWithoutParams = window.location.href.split("?")[0];
+		const sanitizedUrl = urlWithoutParams
+			.replace(/[^\w\s]/gi, "_")
+			.replace(/\s+/g, "_");
+		expect(uniqueKey).to.include(sanitizedUrl);
+	});
+
+	it("should generate explicit instance keys without the browser location", () => {
+		const uniqueKey = generateConfigKey(
+			"datatable",
+			"orders.default",
+			"filter",
+		);
+
+		expect(uniqueKey).to.equal("filter_datatable_orders_default");
+		expect(uniqueKey).to.not.include("example_test");
+	});
+
+	it("should prefer explicit instance keys over legacy URL keys", () => {
+		const uniqueKey = generateComponentConfigKey(
+			"datatable",
+			"dom-id",
+			"stored-order",
+			{
+				instanceKey: "orders.default",
+			},
+		);
+
+		expect(uniqueKey).to.equal("stored_order_datatable_orders_default");
+		expect(uniqueKey).to.not.include("dom-id");
+		expect(uniqueKey).to.not.include("example_test");
+	});
+});

package/test/web/import.js

@@ -25,8 +25,10 @@ import "../cases/components/notify/message.mjs";
 import "../cases/components/notify/notify.mjs";
 import "../cases/components/host/host.mjs";
 import "../cases/components/host/overlay.mjs";
+import "../cases/components/host/config-manager.mjs";
 import "../cases/components/host/util.mjs";
 import "../cases/components/host/details.mjs";
+import "../cases/components/datatable/config-keys.mjs";
 import "../cases/components/datatable/writeback-sanitizer.mjs";
 import "../cases/components/datatable/pagination.mjs";
 import "../cases/components/navigation/site-navigation.mjs";