@schukai/monster 4.154.0 → 4.154.2

package/source/components/layout/tabs.mjs

@@ -432,7 +432,7 @@ class Tabs extends CustomElement {
 	/**
 	 * This method is called internal and should not be called directly.
 	 * @param tabId
-	 * @returns {Tabs}
+	 * @return {Tabs}
 	 */
 	removeTab(tabId) {
 		const tabs = getAllTabPanels.call(this);
@@ -452,7 +452,7 @@ class Tabs extends CustomElement {
 
 	/**
 	 * This method is called internal and should not be called directly.
-	 * @returns {[]}
+	 * @return {[]}
 	 */
 	getTabs() {
 		return getAllTabPanels.call(this).filter((node) => isTabAvailable(node));
@@ -461,11 +461,8 @@ class Tabs extends CustomElement {
 	/**
 	 * This method is called internal and should not be called directly.
 	 * @param content
-	 * @param active
-	 * @param label
-	 * @param tabId
-	 * @param removable
-	 * @returns {Tabs}
+	 * @param {object} options Options for active state, label, tab ID and removability.
+	 * @return {Tabs}
 	 */
 	addTab(
 		content,
@@ -679,7 +676,7 @@ class Tabs extends CustomElement {
 
 /**
  * @private
- * @returns {object}
+ * @return {object}
  */
 function getTranslations() {
 	const locale = getLocaleOfDocument();

package/source/components/layout/utils/attach-tabs-hash-sync.mjs

@@ -31,7 +31,7 @@ export function attachTabsHashSync(
 
 	/**
 	 * Reads active and all tab IDs from the URL hash.
-	 * @returns {{activeTabId: string|null, allTabIds: string[]}}
+	 * @return {{activeTabId: string|null, allTabIds: string[]}}
 	 */
 	function getTabStateFromHash() {
 		const hashObj = parseBracketedKeyValueHash(location.hash);

package/source/components/layout/vertical-tabs.mjs

@@ -291,7 +291,7 @@ class VerticalTabs extends CustomElement {
 	/**
 	 * This method is called internal and should not be called directly.
 	 * @param tabId
-	 * @returns {VerticalTabs}
+	 * @return {VerticalTabs}
 	 */
 	removeTab(tabId) {
 		const tabs = this.getTabs();
@@ -311,7 +311,7 @@ class VerticalTabs extends CustomElement {
 
 	/**
 	 * This method is called internal and should not be called directly.
-	 * @returns {[]}
+	 * @return {[]}
 	 */
 	getTabs() {
 		const nodes = getSlottedElements.call(this);
@@ -327,11 +327,8 @@ class VerticalTabs extends CustomElement {
 	/**
 	 * This method is called internal and should not be called directly.
 	 * @param content
-	 * @param active
-	 * @param label
-	 * @param tabId
-	 * @param removable
-	 * @returns {VerticalTabs}
+	 * @param {object} options Options for active state, label, tab ID and removability.
+	 * @return {VerticalTabs}
 	 */
 	addTab(
 		content,
@@ -487,7 +484,7 @@ class VerticalTabs extends CustomElement {
 
 /**
  * @private
- * @returns {object}
+ * @return {object}
  */
 function getTranslations() {
 	const locale = getLocaleOfDocument();

package/source/components/navigation/site-navigation.mjs

@@ -598,7 +598,7 @@ function setupSubmenu(parentLi, context = "visible", level = 1) {
  * for styling and handling active states.
  * @private
  * @param {HTMLLIElement} item The original list item to clone.
- * @returns {HTMLLIElement} The cloned and configured list item.
+ * @return {HTMLLIElement} The cloned and configured list item.
  */
 function cloneNavItem(item) {
 	const liClone = item.cloneNode(true);
@@ -893,7 +893,7 @@ function populateTabs() {
  * A simple template literal tag function for clarity.
  * @private
  * @param {TemplateStringsArray} strings
- * @returns {string} The combined string.
+ * @return {string} The combined string.
  */
 function html(strings) {
 	return strings.join("");
@@ -902,7 +902,7 @@ function html(strings) {
 /**
  * Returns the HTML template for the component's shadow DOM.
  * @private
- * @returns {string} The HTML template string.
+ * @return {string} The HTML template string.
  */
 function getTemplate() {
 	return html`<div data-monster-role="control" part="control">

package/source/components/navigation/table-of-content.mjs

@@ -300,7 +300,7 @@ function removeNavigationScrollBinding() {
 /**
  * @private
  * @param element
- * @returns {number|number|*|number}
+ * @return {number|number|*|number}
  */
 function getScrollHeight(element) {
 	if (element instanceof ShadowRoot) {

package/source/components/navigation/wizard-navigation.mjs

@@ -86,9 +86,8 @@ class WizardNavigation extends CustomElement {
 	/**
 	 * Navigates to the specified main step if the transition logic allows it.
 	 * @param {number} index The index of the target step.
-	 * @param {object} [options={}] Additional options.
-	 * @param {boolean} [options.force=false] If true, the `beforeStepChange` callback is skipped.
-	 * @returns {Promise<void>}
+	 * @param {object} [options={}] Set `force` to skip the `beforeStepChange` callback.
+	 * @return {Promise<void>}
 	 * @fires monster-wizard-step-changed
 	 */
 	async goToStep(index, options = {}) {
@@ -175,9 +174,8 @@ class WizardNavigation extends CustomElement {
 	 * Activates a specific main step and sub-step.
 	 * @param {number} mainIndex The index of the main step.
 	 * @param {number} subIndex The index of the sub-step.
-	 * @param {object} [options={}] Additional options.
-	 * @param {boolean} [options.force=false] If true, the `beforeStepChange` callback is skipped.
-	 * @returns {Promise<void>}
+	 * @param {object} [options={}] Set `force` to skip the `beforeStepChange` callback.
+	 * @return {Promise<void>}
 	 * @fires monster-wizard-substep-changed
 	 */
 	async activate(mainIndex, subIndex, options = {}) {
@@ -232,7 +230,7 @@ class WizardNavigation extends CustomElement {
 
 	/**
 	 * Navigates to the next step or sub-step in sequence.
-	 * @returns {Promise<void>}
+	 * @return {Promise<void>}
 	 */
 	async next() {
 		const mainIndex = this[currentStepIndexSymbol];
@@ -261,7 +259,7 @@ class WizardNavigation extends CustomElement {
 
 	/**
 	 * Navigates to the previous step or sub-step in sequence.
-	 * @returns {Promise<void>}
+	 * @return {Promise<void>}
 	 */
 	async previous() {
 		const mainIndex = this[currentStepIndexSymbol];
@@ -286,7 +284,7 @@ class WizardNavigation extends CustomElement {
 
 	/**
 	 * Marks the current step as completed and automatically navigates to the next step.
-	 * @returns {Promise<void>}
+	 * @return {Promise<void>}
 	 */
 	async completeAndNext() {
 		const currentIndex = this[currentStepIndexSymbol];
@@ -341,7 +339,7 @@ class WizardNavigation extends CustomElement {
 
 	/**
 	 * Gets the index of the currently active main step.
-	 * @returns {number} The index of the current step, or -1 if none is active.
+	 * @return {number} The index of the current step, or -1 if none is active.
 	 */
 	getCurrentStepIndex() {
 		return this[currentStepIndexSymbol];
@@ -349,7 +347,7 @@ class WizardNavigation extends CustomElement {
 
 	/**
 	 * Gets the index of the currently active sub-step within the main step.
-	 * @returns {number} The index of the current sub-step, or -1 if none is active.
+	 * @return {number} The index of the current sub-step, or -1 if none is active.
 	 */
 	getCurrentSubStepIndex() {
 		return this[currentSubStepIndexSymbol];

package/source/components/notify/monitor-attribute-errors.mjs

@@ -52,7 +52,7 @@ const mutationObserversSymbol = Symbol("mutationObservers");
 class MonitorAttributeErrors extends CustomElement {
 	/**
 	 * This method is called by the `instanceof` operator.
-	 * @returns {symbol}
+	 * @return {symbol}
 	 */
 	static get [instanceSymbol]() {
 		return Symbol.for(

package/source/components/time/day.mjs

@@ -75,7 +75,7 @@ class Day extends CustomElement {
 
 	/**
 	 * This method is called by the `instanceof` operator.
-	 * @returns {symbol}
+	 * @return {symbol}
 	 */
 	static get [instanceSymbol]() {
 		return Symbol.for("@schukai/monster/components/time/day@@instance");

package/source/components/time/month-calendar.mjs

@@ -80,7 +80,7 @@ const boundDaysSymbol = Symbol("boundDays");
 class MonthCalendar extends CustomElement {
 	/**
 	 * This method is called by the `instanceof` operator.
-	 * @returns {symbol}
+	 * @return {symbol}
 	 */
 	static get [instanceSymbol]() {
 		return Symbol.for("@schukai/monster/components/time/calendar@@instance");
@@ -216,7 +216,7 @@ class MonthCalendar extends CustomElement {
 
 /**
  * @private
- * @returns {object}
+ * @return {object}
  */
 function getTranslations() {
 	const locale = getLocaleOfDocument();
@@ -312,7 +312,7 @@ function getTranslations() {
  * @param {Date} appointmentStart - Start date of the appointment.
  * @param {Date} appointmentEnd - End date of the appointment (inclusive).
  * @param {Date} calendarGridStart - The first day of the calendar grid (e.g., the Monday from generateCalendarData()).
- * @returns {number[]} Array indicating how many days the appointment spans per row.
+ * @return {number[]} Array indicating how many days the appointment spans per row.
  *
  * Example:
  * - Appointment: 01.03.2025 (Saturday) to 01.03.2025:
@@ -360,7 +360,7 @@ function getAppointmentRowsUsingCalendar(
 /**
  * @private
  * @param format
- * @returns {*[]}
+ * @return {*[]}
  */
 function getWeekdays(format = "long") {
 	// Intl needs the language tag. Handing it the Locale instance makes
@@ -393,7 +393,7 @@ function getWeekdays(format = "long") {
  *     {"columns":7,"label":"03/11/2025 - 04/05/2025","start":"2025-03-24","startIndex":28},
  *     {"columns":6,"label":"03/11/2025 - 04/05/2025","start":"2025-03-31","startIndex":35}
  *   ]
- * @returns {Array} The segments with assigned "line" property
+ * @return {Array} The segments with assigned "line" property
  */
 function assignLinesToSegments(segments) {
 	const groups = {};
@@ -747,7 +747,7 @@ function placeAppointments() {
 
 /**
  * @private
- * @returns {{maxHeaderHeight: number, maxFooterHeight: number}}
+ * @return {{maxHeaderHeight: number, maxFooterHeight: number}}
  */
 function calcHeaderAndFooterHeight() {
 	let maxHeaderHeight = 0;
@@ -812,7 +812,7 @@ function calcHeaderAndFooterHeight() {
  * Generates two arrays: one for the calendar grid (42 days) and one for the weekday headers (7 days).
  * The grid always starts on the Monday of the week that contains the first of the given month.
  *
- * @returns {Object} An object containing:
+ * @return {Object} An object containing:
  *                   - calendarDays: Array of 42 objects, each representing a day.
  *                   - calendarWeekdays: Array of seven objects, each representing a weekday header.
  */
@@ -945,7 +945,7 @@ function refreshCalendar() {
  * @param {Array} appointments - Array of appointment objects. Expected properties: "startDate" and "endDate".
  * @param {Date|string} start - Calendar start date.
  * @param {Date|string} end - Calendar end date.
- * @returns {Object} A map in the format { "YYYY-MM-DD": [appointment1, appointment2, ...] }
+ * @return {Object} A map in the format { "YYYY-MM-DD": [appointment1, appointment2, ...] }
  */
 function getAppointmentsPerDay(appointments, start, end) {
 	const appointmentsMap = {};

package/source/components/time/timeline/appointment.mjs

@@ -41,7 +41,7 @@ const controlElementSymbol = Symbol("calendarElement");
 class Appointment extends CustomElement {
 	/**
 	 * This method is called by the `instanceof` operator.
-	 * @returns {symbol}
+	 * @return {symbol}
 	 */
 	static get [instanceSymbol]() {
 		return Symbol.for(

package/source/components/time/timeline/segment.mjs

@@ -54,7 +54,7 @@ const controlElementSymbol = Symbol("calendarElement");
 class Segment extends CustomElement {
 	/**
 	 * This method is called by the `instanceof` operator.
-	 * @returns {symbol}
+	 * @return {symbol}
 	 */
 	static get [instanceSymbol]() {
 		return Symbol.for(

package/source/components/tree-menu/tree-menu.mjs

@@ -216,7 +216,6 @@ class TreeMenu extends CustomElement {
 
 	/**
 	 * @param {string} value
-	 * @param value
 	 */
 	selectEntry(value) {
 		this.shadowRoot

package/source/data/datasource/dom.mjs

@@ -24,6 +24,7 @@ export { DomStorage };
  *
  * @license AGPLv3
  * @copyright Volker Schukai
+ * @summary Stores datasource records in memory.
  */
 class DomStorage extends Datasource {
 	/**

package/source/dom/customelement.mjs

@@ -313,7 +313,7 @@ class CustomElement extends HTMLElement {
 	/**
 	 * Returns whether the host element is currently visible.
 	 *
-	 * @returns {boolean}
+	 * @return {boolean}
 	 */
 	get visible() {
 		return !this.hidden;
@@ -322,7 +322,7 @@ class CustomElement extends HTMLElement {
 	/**
 	 * Alias for the current host visibility state.
 	 *
-	 * @returns {boolean}
+	 * @return {boolean}
 	 */
 	get isVisible() {
 		return this.visible;
@@ -333,7 +333,7 @@ class CustomElement extends HTMLElement {
 	 * 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}
+	 * @return {Map}
 	 */
 	get customization() {
 		return new Map();
@@ -587,7 +587,7 @@ class CustomElement extends HTMLElement {
 	/**
 	 * Shows the host element.
 	 *
-	 * @returns {CustomElement}
+	 * @return {CustomElement}
 	 */
 	show() {
 		return this.setVisible(true);
@@ -596,7 +596,7 @@ class CustomElement extends HTMLElement {
 	/**
 	 * Hides the host element.
 	 *
-	 * @returns {CustomElement}
+	 * @return {CustomElement}
 	 */
 	hide() {
 		return this.setVisible(false);
@@ -606,7 +606,7 @@ class CustomElement extends HTMLElement {
 	 * Sets the host visibility.
 	 *
 	 * @param {boolean} visible
-	 * @returns {CustomElement}
+	 * @return {CustomElement}
 	 */
 	setVisible(visible) {
 		if (visible) {
@@ -622,7 +622,7 @@ class CustomElement extends HTMLElement {
 	 * Toggles the host visibility.
 	 *
 	 * @param {boolean} [force]
-	 * @returns {CustomElement}
+	 * @return {CustomElement}
 	 */
 	toggleVisibility(force) {
 		if (typeof force === "boolean") {
@@ -1720,7 +1720,7 @@ function getManagedShadowRoot() {
 /**
  * @private
  * @param html
- * @returns {*|string}
+ * @return {*|string}
  */
 function substituteI18n(html) {
 	if (!this.getOption("templateFormatter.i18n", false)) {
@@ -1761,7 +1761,7 @@ function initHtmlContent() {
 
 /**
  * @private
- * @returns {void}
+ * @return {void}
  */
 function syncVisibilityState() {
 	const visible = !this.hidden;
@@ -1787,7 +1787,7 @@ function syncVisibilityState() {
 
 /**
  * @private
- * @returns {void}
+ * @return {void}
  */
 function blurFocusedElement() {
 	const shadowRoot = getManagedShadowRoot.call(this);
@@ -1814,7 +1814,7 @@ function blurFocusedElement() {
 /**
  * @private
  * @param {boolean} visible
- * @returns {void}
+ * @return {void}
  */
 function dispatchVisibilityChangedEvent(visible) {
 	this.dispatchEvent(
@@ -1889,7 +1889,7 @@ function initCSSStylesheet() {
 
 /**
  * @private
- * @returns {CSSStyleSheet}
+ * @return {CSSStyleSheet}
  */
 function getHostVisibilityStyleSheet() {
 	if (hostVisibilityStyleSheet instanceof CSSStyleSheet) {
@@ -1907,7 +1907,7 @@ function getHostVisibilityStyleSheet() {
 /**
  * @private
  * @param {ShadowRoot} shadowRoot
- * @returns {void}
+ * @return {void}
  */
 function appendVisibilityHostStyle(shadowRoot) {
 	if (!(shadowRoot instanceof ShadowRoot)) {

package/source/dom/sanitize-html.mjs

@@ -2,7 +2,7 @@
  * Helper function to sanitize HTML content by removing potentially dangerous content.
  * @param {string} htmlString - The HTML string to sanitize.
  * @param {Object} [options={}] - Optional configuration options.
- * @returns {string} The sanitized HTML string.
+ * @return {string} The sanitized HTML string.
  */
 export function sanitizeHtml(htmlString, options = {}) {
 	const parser = new DOMParser();

package/source/i18n/internal.mjs

@@ -23,7 +23,7 @@ getInternalTranslations();
 
 /**
  *
- * @returns {*|Translations}
+ * @return {*|Translations}
  */
 function getInternalTranslations() {
 	if (internalTranslations) {
@@ -170,7 +170,7 @@ function getInternalTranslations() {
 /**
  * Returns the internal localization message.
  * @param message
- * @returns {string}
+ * @return {string}
  */
 
 function getInternalLocalizationMessage(message) {

package/source/i18n/providers/embed.mjs

@@ -147,7 +147,7 @@ class Embed extends Provider {
 	 * `script[data-monster-role=translations]` is searched for and the translations are assigned to the element.
 	 *
 	 * @param element
-	 * @returns {Promise<Awaited<*[]>>|Promise<Awaited<unknown>[]>}
+	 * @return {Promise<Awaited<*[]>>|Promise<Awaited<unknown>[]>}
 	 */
 	static assignTranslationsToElement(element) {
 		const d = getDocument();

package/source/i18n/time-ago.mjs

@@ -19,7 +19,7 @@ export { formatTimeAgo };
  *
  * @param date
  * @param locale
- * @returns {string}
+ * @return {string}
  */
 function formatTimeAgo(date, locale) {
 	const now = new Date(Math.floor(new Date().getTime() / 1000) * 1000);

package/source/text/formatter.mjs

@@ -121,6 +121,7 @@ const workingDataSymbol = Symbol("workingData");
  * @license AGPLv3
  * @since 1.12.0
  * @copyright Volker Schukai
+ * @summary Formats placeholder-based messages from structured values and pipes.
  */
 class Formatter extends BaseWithOptions {
 	/**

package/source/types/dataurl.mjs

@@ -37,6 +37,7 @@ const internal = Symbol("internal");
  * @copyright Volker Schukai
  * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URIs
  * @see https://datatracker.ietf.org/doc/html/rfc2397
+ * @summary Parses and represents data URLs with media type and content.
  */
 class DataUrl extends Base {
 	/**

package/source/types/has.mjs

@@ -19,7 +19,7 @@ export { hasImplementation };
  *
  * @param object
  * @param methods
- * @returns {boolean}
+ * @return {boolean}
  */
 function hasImplementation(object, methods) {
 	return methods.every((method) => typeof object[method] === "function");

package/source/types/is.mjs

@@ -33,7 +33,7 @@ export {
 /**
  * Checks whether the value passed is a DOM Element.
  * @param {*} value
- * @returns {boolean}
+ * @return {boolean}
  */
 function isElement(value) {
 	if (typeof Element === "undefined") {
@@ -46,7 +46,7 @@ function isElement(value) {
  * Checks whether the value passed is a Proxy.
  *
  * @param {*} value
- * @returns {boolean}
+ * @return {boolean}
  */
 function isProxy(value) {
 	return value?.[proxyInstanceMarker] === proxyInstanceMarker;

package/source/types/mediatype.mjs

@@ -36,6 +36,7 @@ const internal = Symbol("internal");
  * @license AGPLv3
  * @since 1.8.0
  * @copyright Volker Schukai
+ * @summary Parses and represents media types and their parameters.
  */
 class MediaType extends Base {
 	/**

package/source/types/observer.mjs

@@ -75,7 +75,7 @@ class Observer extends Base {
 
 	/**
 	 * This method is called by the `instanceof` operator.
-	 * @returns {symbol}
+	 * @return {symbol}
 	 * @since 2.1.0
 	 */
 	static get [instanceSymbol]() {
@@ -97,7 +97,7 @@ class Observer extends Base {
 	 * the callback is only executed once. All callers will receive the same promise.
 	 *
 	 * @param {object} subject The subject object that triggered the update.
-	 * @returns {Promise<*>} A promise that resolves with the return value of the callback,
+	 * @return {Promise<*>} A promise that resolves with the return value of the callback,
 	 * or rejects if the callback throws an error.
 	 */
 	update(subject) {
@@ -129,7 +129,7 @@ class Observer extends Base {
 
 	/**
 	 * @param {string} tag
-	 * @returns {Observer}
+	 * @return {Observer}
 	 */
 	addTag(tag) {
 		this.#tags.add(tag);
@@ -138,7 +138,7 @@ class Observer extends Base {
 
 	/**
 	 * @param {string} tag
-	 * @returns {Observer}
+	 * @return {Observer}
 	 */
 	removeTag(tag) {
 		this.#tags.remove(tag);
@@ -146,7 +146,7 @@ class Observer extends Base {
 	}
 
 	/**
-	 * @returns {string[]}
+	 * @return {string[]}
 	 */
 	getTags() {
 		return this.#tags.entries();
@@ -154,7 +154,7 @@ class Observer extends Base {
 
 	/**
 	 * @param {string} tag
-	 * @returns {boolean}
+	 * @return {boolean}
 	 */
 	hasTag(tag) {
 		return this.#tags.contains(tag);

package/source/types/observerlist.mjs

@@ -23,6 +23,7 @@ export { ObserverList };
  *
  * @license AGPLv3
  * @since 1.0.0
+ * @summary Manages a collection of Observer instances.
  */
 class ObserverList extends Base {
 	/**

package/source/types/proxyobserver.mjs

@@ -33,6 +33,7 @@ export { ProxyObserver };
  * @license AGPLv3
  * @since 1.0.0
  * @copyright Volker Schukai
+ * @summary Observes nested object changes through a proxy.
  */
 class ProxyObserver extends Base {
 	/**

package/source/types/stack.mjs

@@ -22,6 +22,7 @@ export { Stack };
  * @license AGPLv3
  * @since 1.4.0
  * @copyright Volker Schukai
+ * @summary Provides a last-in, first-out collection.
  */
 class Stack extends Base {
 	/**

package/source/types/tokenlist.mjs

@@ -28,6 +28,7 @@ export { TokenList };
  * @license AGPLv3
  * @since 1.2.0
  * @copyright Volker Schukai
+ * @summary Manages a whitespace-separated set of string tokens.
  */
 class TokenList extends Base {
 	/**

package/source/types/uuid.mjs

@@ -27,6 +27,7 @@ export { UUID };
  * @since 1.25.0
  * @copyright Volker Schukai
  * @throws {Error} unsupported
+ * @summary Creates and retrieves stable UUIDs for objects.
  */
 class UUID extends Base {
 	/**

package/source/util/accessiblecolor.mjs

@@ -91,7 +91,7 @@
  *
  * @param color
  * @param minContrast
- * @returns {string|string}
+ * @return {string|string}
  * @summary This function generates a color that meets the WCAG contrast ratio requirements against a given base color.
  */
 export function accessibleColor(color, minContrast = 4.5) {
@@ -187,7 +187,7 @@ function luminance(hex) {
  *
  * @param {number} l1 - The relative luminance of the lighter element.
  * @param {number} l2 - The relative luminance of the darker element.
- * @returns {number} The contrast ratio, a value ranging from 1 to 21.
+ * @return {number} The contrast ratio, a value ranging from 1 to 21.
  */
 const contrastRatio = (l1, l2) =>
 	(Math.max(l1, l2) + 0.05) / (Math.min(l1, l2) + 0.05);