@schukai/monster 4.11.1 → 4.13.0

package/source/components/data/metric-graph.mjs

@@ -42,9 +42,9 @@ export const metricGraphControlElementSymbol = Symbol(
 /**
  * A MetricGraph
  *
- * @fragments /fragments/data/metric-graph/
+ * @fragments /fragments/components/data/metric-graph/
  *
- * @example /examples/data/metric-graph-simple
+ * @example /examples/components/data/metric-graph-simple
  *
  * @since 4.11.0
  * @copyright schukai GmbH
@@ -60,7 +60,7 @@ class MetricGraph extends CustomElement {
 	}
 
 	/**
-	 * @return {Components.Data.Metric
+	 * @return {MetricGraph}
 	 */
 	[assembleMethodSymbol]() {
 		super[assembleMethodSymbol]();

package/source/components/data/metric.mjs

@@ -56,7 +56,7 @@ class Metric extends CustomElement {
 	}
 
 	/**
-	 * @return {Components.Data.Metric
+	 * @return {Metric}
 	 */
 	[assembleMethodSymbol]() {
 		super[assembleMethodSymbol]();

package/source/components/datatable/filter.mjs

@@ -71,6 +71,7 @@ import "../form/context-error.mjs";
 import "../form/message-state-button.mjs";
 
 import { getLocaleOfDocument } from "../../dom/locale.mjs";
+import { normalizeNumber } from "../../i18n/util.mjs";
 
 export { Filter };
 
@@ -1259,6 +1260,27 @@ function collectSearchQueries() {
 							// return query as url encoded
 							return encodeURIComponent(query);
 						},
+						"to-int-2": (value, key) => {
+							const query = normalizeNumber(value);
+							if (Number.isNaN(query)) {
+								return key + " IS NULL";
+							}
+							return key + "=" + encodeURIComponent(Math.round(query * 100));
+						},
+						"to-int-3": (value, key) => {
+							const query = normalizeNumber(value);
+							if (Number.isNaN(query)) {
+								return "";
+							}
+							return key + "=" + encodeURIComponent(Math.round(query * 1000));
+						},
+						"to-int-4": (value, key) => {
+							const query = normalizeNumber(value);
+							if (Number.isNaN(query)) {
+								return "";
+							}
+							return key + "=" + encodeURIComponent(Math.round(query * 10000));
+						},
 					},
 				});
 

package/source/components/form/message-state-button.mjs

@@ -35,19 +35,20 @@ export { MessageStateButton };
 const buttonElementSymbol = Symbol("buttonElement");
 
 /**
- * A select control that can be used to select one or more options from a list.
+ * A specialized button component that combines state management with message display capabilities.
+ * It extends the Popper component to show messages in a popup overlay and can be used for form submissions
+ * or manual actions.
  *
  * @fragments /fragments/components/form/message-state-button/
- *
  * @example /examples/components/form/message-state-button-simple
  *
  * @since 2.11.0
  * @copyright schukai GmbH
- * @summary A beautiful select control that can make your life easier and also looks good.
- * @fires monster-options-set
- * @fires monster-selected
- * @fires monster-change
- * @fires monster-changed
+ * @summary Button component with integrated message display and state management
+ * @fires monster-state-changed - Fired when button state changes
+ * @fires monster-message-shown - Fired when message is displayed
+ * @fires monster-message-hidden - Fired when message is hidden
+ * @fires monster-click - Fired when button is clicked
  */
 class MessageStateButton extends Popper {
 	/**
@@ -61,12 +62,12 @@ class MessageStateButton extends Popper {
 	}
 
 	/**
+	 * Sets the state of the button which affects its visual appearance
 	 *
-	 * @param {string} state
-	 * @param {number} timeout
-	 * @return {MessageStateButton}
-	 * @throws {TypeError} value is not a string
-	 * @throws {TypeError} value is not an instance
+	 * @param {string} state - The state to set (e.g. 'success', 'error', 'loading')
+	 * @param {number} timeout - Optional timeout in milliseconds after which state is removed
+	 * @return {MessageStateButton} Returns the button instance for chaining
+	 * @throws {TypeError} When state is not a string or timeout is not a number
 	 */
 	setState(state, timeout) {
 		return this[buttonElementSymbol].setState(state, timeout);
@@ -164,12 +165,13 @@ class MessageStateButton extends Popper {
 	}
 
 	/**
-	 * Sets the message
+	 * Sets the message content to be displayed in the popup overlay
 	 *
-	 * @param {string|HTMLElement}message
-	 * @param {string} title
-	 * @param {string} icon
-	 * @return {MessageStateButton}
+	 * @param {string|HTMLElement} message - The message content as string or HTML element
+	 * @param {string} title - Optional title to show above the message
+	 * @param {string} icon - Optional icon HTML to display next to the title
+	 * @return {MessageStateButton} Returns the button instance for chaining
+	 * @throws {TypeError} When message is empty or invalid type
 	 */
 	setMessage(message, title, icon) {
 		if (isString(message)) {
@@ -230,10 +232,10 @@ class MessageStateButton extends Popper {
 	}
 
 	/**
-	 * With this method you can show the popper with timeout feature.
+	 * Shows the message popup overlay with optional auto-hide timeout
 	 *
-	 * @param {number} timeout
-	 * @return {MessageStateButton}
+	 * @param {number} timeout - Optional time in milliseconds after which the message will auto-hide
+	 * @return {MessageStateButton} Returns the button instance for chaining
 	 */
 	showMessage(timeout) {
 		this.showDialog.call(this);
@@ -248,7 +250,7 @@ class MessageStateButton extends Popper {
 	}
 
 	/**
-	 * With this method you can show the popper.
+	 * With this method, you can show the popper.
 	 *
 	 * @return {MessageStateButton}
 	 */
@@ -306,10 +308,12 @@ class MessageStateButton extends Popper {
 	}
 
 	/**
-	 * The Button.click() method simulates a click on the internal button element.
+	 * Programmatically triggers a click event on the button
+	 * Will not trigger if button is disabled
 	 *
 	 * @since 3.27.0
 	 * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/click}
+	 * @fires monster-click
 	 */
 	click() {
 		if (this.getOption("disabled") === true) {

package/source/components/layout/popper.mjs

@@ -34,53 +34,60 @@ import { isArray } from "../../types/is.mjs";
 export { Popper };
 
 /**
+ * Symbol for timer callback reference
  * @private
  * @type {symbol}
  */
 const timerCallbackSymbol = Symbol("timerCallback");
 
 /**
- * local symbol
+ * Symbol for resize observer reference
  * @private
  * @type {symbol}
  */
 const resizeObserverSymbol = Symbol("resizeObserver");
 
 /**
- * local symbol
+ * Symbol for close event handler reference
  * @private
  * @type {symbol}
  */
 const closeEventHandler = Symbol("closeEventHandler");
 
 /**
+ * Symbol for control element reference
  * @private
  * @type {symbol}
  */
 const controlElementSymbol = Symbol("controlElement");
 
 /**
+ * Symbol for button element reference
  * @private
  * @type {symbol}
  */
 const buttonElementSymbol = Symbol("buttonElement");
 
 /**
- * local symbol
+ * Symbol for popper element reference
  * @private
  * @type {symbol}
  */
 const popperElementSymbol = Symbol("popperElement");
 
 /**
- * local symbol
+ * Symbol for arrow element reference
  * @private
  * @type {symbol}
  */
 const arrowElementSymbol = Symbol("arrowElement");
 
 /**
- * A Popper is a floating UI element that can be shown or hidden.
+ * Popper component for displaying floating UI elements
+ *
+ * The Popper class creates a floating overlay element that can be shown/hidden
+ * and positioned relative to a trigger element. It supports different interaction
+ * modes like click, hover, focus etc.
  *
  * @fragments /fragments/components/layout/popper/
  *
@@ -89,36 +96,34 @@ const arrowElementSymbol = Symbol("arrowElement");
  *
  * @since 1.65.0
  * @copyright schukai GmbH
- * @summary A beautiful popper that can make your life easier and also looks good.
- * @fires monster-popper-hide fired when the popper is hide.
- * @fires monster-popper-hidden fired when the popper is hidden.
- * @fires monster-popper-open fired when the popper is open.
- * @fires monster-popper-opened fired when the popper is opened.
+ * @summary Floating overlay component with flexible positioning and interaction modes
+ * @fires monster-popper-hide - Fired when popper starts hiding
+ * @fires monster-popper-hidden - Fired when popper is fully hidden
+ * @fires monster-popper-open - Fired when popper starts opening
+ * @fires monster-popper-opened - Fired when popper is fully opened
  */
 class Popper extends CustomElement {
 	/**
-	 * This method is called by the `instanceof` operator.
-	 * @return {symbol}
+	 * Gets the instance symbol for type checking
+	 * @return {symbol} The instance type symbol
 	 */
 	static get [instanceSymbol]() {
 		return Symbol.for("@schukai/monster/components/layout/popper@@instance");
 	}
 
 	/**
-	 * To set the options via the HTML tag, the attribute `data-monster-options` must be used.
-	 * @see {@link https://monsterjs.org/en/doc/#configurate-a-monster-control}
-	 *
-	 * The individual configuration values can be found in the table.
+	 * Default configuration options for the popper
 	 *
-	 * @property {Object} templates The templates for the control.
-	 * @property {string} templates.main The main template.
-	 * @property {string} mode The mode of the popper. Possible values are `click`, `enter`, `manual`, `focus`, "auto" or a combination of them.
-	 * @property {string} content The content of the popper.
-	 * @property {object} popper The popper options.
-	 * @property {string} popper.placement The placement of the popper. Possible values are `top`, `bottom`, `left` and `right`.
-	 * @property {function[]} popper.middleware The middleware functions of the popper.
-	 * @property {Object} features The features of the popper.
-	 * @property {boolean} features.preventOpenEventSent Prevents the open event from being sent.
+	 * @property {Object} templates - Template configuration
+	 * @property {string} templates.main - Main template HTML
+	 * @property {string} mode - Interaction mode(s): click|enter|manual|focus|auto
+	 * @property {string} content - Content template
+	 * @property {Object} popper - Positioning options
+	 * @property {string} popper.placement - Placement: top|bottom|left|right
+	 * @property {Array} popper.middleware - Positioning middleware functions
+	 * @property {Object} features - Feature flags
+	 * @property {boolean} features.preventOpenEventSent - Prevent open event
+	 * @returns {Object} Default options merged with parent defaults
 	 */
 	get defaults() {
 		return Object.assign({}, super.defaults, {
@@ -138,9 +143,9 @@ class Popper extends CustomElement {
 	}
 
 	/**
-	 * This method is called by the `connectedCallback` method on the first call.
-	 *
-	 * @return {void}
+	 * Initialize the component
+	 * Called on first connection to DOM
+	 * @private
 	 */
 	[assembleMethodSymbol]() {
 		super[assembleMethodSymbol]();
@@ -149,27 +154,24 @@ class Popper extends CustomElement {
 	}
 
 	/**
-	 * This method returns the tag name of the element.
-	 *
-	 * @return {string}
+	 * Gets the custom element tag name
+	 * @return {string} The tag name
 	 */
 	static getTag() {
 		return "monster-popper";
 	}
 
 	/**
-	 * This method returns the css styles of the element.
-	 *
-	 * @return {CSSStyleSheet[]}
+	 * Gets component stylesheets
+	 * @return {CSSStyleSheet[]} Array of stylesheets
 	 */
 	static getCSSStyleSheet() {
 		return [PopperStyleSheet];
 	}
 
 	/**
-	 * This method is called when the element is connected to the dom.
-	 *
-	 * @return {void}
+	 * Lifecycle callback when element connects to DOM
+	 * Sets up event listeners and initializes popper
 	 */
 	connectedCallback() {
 		super.connectedCallback();
@@ -177,7 +179,6 @@ class Popper extends CustomElement {
 		const document = getDocument();
 
 		for (const [, type] of Object.entries(["click", "touch"])) {
-			// close on outside ui-events
 			document.addEventListener(type, this[closeEventHandler]);
 		}
 
@@ -186,14 +187,12 @@ class Popper extends CustomElement {
 	}
 
 	/**
-	 * This method is called when the element is disconnected from the dom.
-	 *
-	 * @return {void}
+	 * Lifecycle callback when element disconnects from DOM
+	 * Cleans up event listeners and observers
 	 */
 	disconnectedCallback() {
 		super.disconnectedCallback();
 
-		// close on outside ui-events
 		for (const [, type] of Object.entries(["click", "touch"])) {
 			document.removeEventListener(type, this[closeEventHandler]);
 		}
@@ -202,9 +201,8 @@ class Popper extends CustomElement {
 	}
 
 	/**
-	 * With this method, you can show the popper.
-	 *
-	 * @return {Popper}
+	 * Shows the popper element
+	 * @return {Popper} The popper instance
 	 */
 	showDialog() {
 		show.call(this);
@@ -212,9 +210,8 @@ class Popper extends CustomElement {
 	}
 
 	/**
-	 * With this method you can hide the popper.
-	 *
-	 * @return {Popper}
+	 * Hides the popper element
+	 * @return {Popper} The popper instance
 	 */
 	hideDialog() {
 		hide.call(this);
@@ -222,9 +219,8 @@ class Popper extends CustomElement {
 	}
 
 	/**
-	 * With this method you can toggle the popper.
-	 *
-	 * @return {Popper}
+	 * Toggles popper visibility
+	 * @return {Popper} The popper instance
 	 */
 	toggleDialog() {
 		if (this[popperElementSymbol].style.display === STYLE_DISPLAY_MODE_BLOCK) {
@@ -237,8 +233,9 @@ class Popper extends CustomElement {
 }
 
 /**
+ * Initializes event handlers for popper interactivity
  * @private
- * @return {Popper}
+ * @return {Popper} The popper instance
  */
 function initEventHandler() {
 	this[closeEventHandler] = (event) => {
@@ -276,10 +273,11 @@ function initEventHandler() {
 }
 
 /**
+ * Sets up event handlers for specific interaction mode
  * @private
- * @param mode
- * @return {Popper}
- * @throws Error
+ * @param {string} mode - Interaction mode to initialize
+ * @return {Popper} The popper instance
+ * @throws {Error} For unknown modes
  */
 function initEventHandlerByMode(mode) {
 	switch (mode) {
@@ -338,10 +336,10 @@ function initEventHandlerByMode(mode) {
 }
 
 /**
+ * Sets up resize observer for popper repositioning
  * @private
  */
 function attachResizeObserver() {
-	// against flickering
 	this[resizeObserverSymbol] = new ResizeObserver((entries) => {
 		if (this[timerCallbackSymbol] instanceof DeadMansSwitch) {
 			try {
@@ -369,6 +367,10 @@ function attachResizeObserver() {
 	});
 }
 
+/**
+ * Disconnects resize observer
+ * @private
+ */
 function disconnectResizeObserver() {
 	if (this[resizeObserverSymbol] instanceof ResizeObserver) {
 		this[resizeObserverSymbol].disconnect();
@@ -376,6 +378,7 @@ function disconnectResizeObserver() {
 }
 
 /**
+ * Hides the popper element
  * @private
  */
 function hide() {
@@ -396,6 +399,7 @@ function hide() {
 }
 
 /**
+ * Shows the popper element
  * @private
  */
 function show() {
@@ -427,6 +431,7 @@ function show() {
 }
 
 /**
+ * Updates popper positioning
  * @private
  */
 function updatePopper() {
@@ -447,8 +452,9 @@ function updatePopper() {
 }
 
 /**
+ * Initializes references to DOM elements
  * @private
- * @return {Popper}
+ * @return {Popper} The popper instance
  */
 function initControlReferences() {
 	this[controlElementSymbol] = this.shadowRoot.querySelector(
@@ -467,22 +473,23 @@ function initControlReferences() {
 }
 
 /**
+ * Gets the main template HTML
  * @private
- * @return {string}
+ * @return {string} Template HTML
  */
 function getTemplate() {
 	// language=HTML
 	return `
-        <div data-monster-role="control" part="control">
-            <slot name="button" data-monster-role="button"></slot>
-
-            <div data-monster-role="popper" part="popper" tabindex="-1" class="monster-color-primary-1">
-                <div data-monster-role="arrow"></div>
-                <div part="content" class="flex" data-monster-replace="path:content">
-                </div>
-            </div>
-        </div>
-    `;
+		<div data-monster-role="control" part="control">
+			<slot name="button" data-monster-role="button"></slot>
+
+			<div data-monster-role="popper" part="popper" tabindex="-1" class="monster-color-primary-1">
+				<div data-monster-role="arrow"></div>
+				<div part="content" class="flex" data-monster-replace="path:content">
+				</div>
+			</div>
+		</div>
+	`;
 }
 
 registerCustomElement(Popper);

package/source/dom/customelement.mjs

@@ -197,9 +197,22 @@ class CustomElement extends HTMLElement {
 		super();
 
 		this[attributeObserverSymbol] = {};
-		this[internalSymbol] = new ProxyObserver({
-			options: initOptionsFromAttributes(this, extend({}, this.defaults)),
-		});
+
+		const options = initOptionsFromAttributes(this, extend({}, this.defaults));
+		if (!isObject(options)) {
+			throw new Error(
+				`The options are not defined correctly in the ${this.getTag()} element.`,
+			);
+		}
+
+		if (this.customization instanceof Map) {
+			const pathfinder = new Pathfinder(options);
+			this.customization.forEach((value, key) => {
+				pathfinder.setVia(key, value);
+			});
+		}
+
+		this[internalSymbol] = new ProxyObserver({ options });
 		this[initMethodSymbol]();
 		initOptionObserver.call(this);
 		this[scriptHostElementSymbol] = [];
@@ -249,6 +262,17 @@ class CustomElement extends HTMLElement {
 		return this;
 	}
 
+	/**
+	 * The `customization` property allows overwriting the defaults.
+	 * Unlike the defaults that expect an object, the customization is a Map.
+	 * This also allows overwriting individual values in a deeper structure
+	 * without having to redefine the entire structure and thus changing the defaults.
+	 * @returns {Map}
+	 */
+	get customization() {
+		return new Map();
+	}
+
 	/**
 	 * The `defaults` property defines the default values for a control. If you want to override these,
 	 * you can use various methods, which are described in the documentation available at

package/source/i18n/util.mjs

@@ -14,6 +14,47 @@
 
 import { languages } from "./map/languages.mjs";
 
+/**
+ * Normalizes a number represented as a string by converting it into a valid floating-point number format,
+ * based on the provided or detected locale. It accounts for different decimal and a thousand separator conventions.
+ *
+ * @param {string} input - The string representation of the number to normalize. May include locale-specific formatting.
+ * @param {string} [locale=navigator.language] - The locale used to determine the decimal separator convention. Defaults to the user's browser locale.
+ * @return {number} The normalized number as a floating-point value. Returns NaN if the input is not a parsable number.
+ */
+export function normalizeNumber(input, locale = navigator.language) {
+	if (input === null || input === undefined) return NaN;
+	if (typeof input === "number") return input; // If input is already a number, return it directly
+	if (typeof input !== "string") return NaN;
+
+	const cleaned = input.trim().replace(/\s/g, "");
+	const decimalSeparator = getDecimalSeparator(locale);
+	let normalized = cleaned;
+
+	if (decimalSeparator === "," && cleaned.includes(".")) {
+		normalized = cleaned.replace(/\./g, "").replace(",", ".");
+	} else if (decimalSeparator === "." && cleaned.includes(",")) {
+		normalized = cleaned.replace(/,/g, "").replace(".", ".");
+	} else if (decimalSeparator === "," && cleaned.includes(",")) {
+		normalized = cleaned.replace(",", ".");
+	}
+
+	const result = parseFloat(normalized);
+	return Number.isNaN(result) ? NaN : result;
+}
+
+/**
+ * Retrieves the decimal separator for a given locale.
+ *
+ * @param {string} [locale=navigator.language] - The locale identifier to determine the decimal separator. Defaults to the user's current locale if not provided.
+ * @return {string} The decimal separator used in the specified locale.
+ */
+function getDecimalSeparator(locale = navigator.language) {
+	const numberWithDecimal = 1.1;
+	const formatted = new Intl.NumberFormat(locale).format(numberWithDecimal);
+	return formatted.replace(/\d/g, "")[0]; // z.B. "," oder "."
+}
+
 /**
  * Determines the user's preferred language based on browser settings and available language options.
  *