@schukai/monster 4.134.0 → 4.136.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.134.0"}
+{"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.136.0"}

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

@@ -466,6 +466,11 @@ function initControlReferences() {
 	this[messageElementSymbol] = this.shadowRoot.querySelector(
 		`[${ATTRIBUTE_ROLE}=message]`,
 	);
+	if (this[popperElementSymbol] instanceof HTMLElement) {
+		this[popperElementSymbol].monsterBeforeFloatingUpdate = () => {
+			applyMeasuredMessageWidth.call(this);
+		};
+	}
 	applyResolvedMessagePresentation.call(this);
 }
 
@@ -868,6 +873,7 @@ function applyMeasuredMessageWidth() {
 		Math.min(measuredWidth || minWidth, maxWidth),
 	);
 
+	popper.dataset.monsterPreferredMaxWidth = `${maxWidth}`;
 	popper.style.width = `${targetWidth}px`;
 	popper.style.minWidth = `${minWidth}px`;
 	popper.style.maxWidth = `${maxWidth}px`;

package/source/components/form/select.mjs

@@ -2453,6 +2453,7 @@ function getOptionElements() {
 function calcAndSetOptionsDimension() {
 	const options = getOptionElements.call(this);
 	const container = this[optionsElementSymbol];
+	const content = this[popperElementSymbol]?.querySelector?.('[part="content"]');
 	if (!(container instanceof HTMLElement && options instanceof NodeList)) {
 		return;
 	}
@@ -2541,8 +2542,17 @@ function calcAndSetOptionsDimension() {
 
 	const domRect = this[controlElementSymbol].getBoundingClientRect();
 
+	this[popperElementSymbol].dataset.monsterPreferredWidth = `${Math.ceil(
+		domRect.width,
+	)}`;
 	this[popperElementSymbol].style.width = `${domRect.width}px`;
+	this[popperElementSymbol].style.minWidth = `${domRect.width}px`;
 	container.style.overflowX = "auto";
+
+	if (content instanceof HTMLElement) {
+		content.style.overflowX = "hidden";
+		content.style.overflowY = "hidden";
+	}
 }
 
 /**
@@ -4429,6 +4439,9 @@ function initControlReferences() {
 	this[popperElementSymbol] = this.shadowRoot.querySelector(
 		`[${ATTRIBUTE_ROLE}=popper]`,
 	);
+	this[popperElementSymbol].monsterBeforeFloatingUpdate = () => {
+		calcAndSetOptionsDimension.call(this);
+	};
 	this[inlineFilterElementSymbol] = this.shadowRoot.querySelector(
 		`[${ATTRIBUTE_ROLE}=filter][name="inline-filter"]`,
 	);

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

@@ -27,6 +27,7 @@ import { isArray, isFunction, isObject, isString } from "../../../types/is.mjs";
 import { Processing } from "../../../util/processing.mjs";
 
 export {
+	applyAdaptiveFloatingElementSize,
 	closePositionedPopper,
 	resolveClippingBoundaryElement,
 	isPositionedPopperOpen,
@@ -35,6 +36,8 @@ export {
 };
 
 const autoUpdateCleanupMap = new WeakMap();
+const settlingFrameMap = new WeakMap();
+const floatingResizeObserverMap = new WeakMap();
 
 /**
  * @private
@@ -67,16 +70,26 @@ function enableFloatingPositioning(controlElement, popperElement, config) {
 	popperElement.style.removeProperty("visibility");
 	popperElement.style.display = "block";
 
+	startFloatingResizeObserver(controlElement, popperElement, config);
 	startAutoUpdate(controlElement, popperElement, () => {
+		runFloatingUpdateHook(popperElement);
 		syncFloatingPopover(controlElement, popperElement, config);
 	});
+	runFloatingUpdateHook(popperElement);
 	syncFloatingPopover(controlElement, popperElement, config);
 }
 
-function syncFloatingPopover(controlElement, popperElement, config) {
+function syncFloatingPopover(
+	controlElement,
+	popperElement,
+	config,
+	allowSettlingPass = true,
+) {
 	const arrowElement = popperElement.querySelector("[data-monster-role=arrow]");
 	const floatingMiddleware = [...config.floatingMiddleware];
 
+	resetAdaptiveFloatingElementSize(popperElement);
+
 	if (
 		arrowElement instanceof HTMLElement &&
 		config.middlewareTokens.includes("arrow")
@@ -101,6 +114,10 @@ function syncFloatingPopover(controlElement, popperElement, config) {
 		if (middlewareData.arrow) {
 			applyFloatingArrowStyles(arrowElement, placement, middlewareData.arrow);
 		}
+
+		if (allowSettlingPass) {
+			scheduleSettlingPass(controlElement, popperElement, config);
+		}
 	});
 }
 
@@ -253,30 +270,249 @@ function createAdaptiveSizeMiddleware(detectOverflowOptions, popperElement) {
 					return;
 				}
 
-				const maxWidth = clampAvailableDimension(
+				applyAdaptiveFloatingElementSize(floatingElement, {
 					availableWidth,
-					readMaxDimension(floatingElement, "maxWidth"),
-				);
-				const maxHeight = clampAvailableDimension(
 					availableHeight,
-					readMaxDimension(floatingElement, "maxHeight"),
-				);
-				const nextStyle = {
-					boxSizing: "border-box",
-				};
+				});
+			},
+		}),
+	);
+}
 
-				if (Number.isFinite(maxWidth) && maxWidth > 0) {
-					nextStyle.maxWidth = `${maxWidth}px`;
-				}
+function applyAdaptiveFloatingElementSize(
+	floatingElement,
+	{ availableWidth, availableHeight },
+) {
+	const maxWidth = clampAvailableDimension(
+		availableWidth,
+		readMaxDimension(floatingElement, "maxWidth"),
+	);
+	const maxHeight = clampAvailableDimension(
+		availableHeight,
+		readMaxDimension(floatingElement, "maxHeight"),
+	);
+	const nextStyle = {
+		boxSizing: "border-box",
+	};
 
-				if (Number.isFinite(maxHeight) && maxHeight > 0) {
-					nextStyle.maxHeight = `${maxHeight}px`;
-				}
+	if (Number.isFinite(maxWidth) && maxWidth > 0) {
+		nextStyle.maxWidth = `${maxWidth}px`;
+	} else {
+		nextStyle.maxWidth = "";
+	}
 
-				Object.assign(floatingElement.style, nextStyle);
-			},
-		}),
+	if (Number.isFinite(maxHeight) && maxHeight > 0) {
+		nextStyle.maxHeight = `${maxHeight}px`;
+	} else {
+		nextStyle.maxHeight = "";
+	}
+
+	Object.assign(floatingElement.style, nextStyle);
+
+	syncPreferredFloatingWidth(floatingElement, maxWidth);
+	syncPreferredFloatingMaxWidth(floatingElement, maxWidth);
+	applyAdaptiveFloatingContentSize(floatingElement, maxHeight);
+}
+
+function applyAdaptiveFloatingContentSize(floatingElement, maxHeight) {
+	const contentElement = getFloatingContentElement(floatingElement);
+	if (!(contentElement instanceof HTMLElement)) {
+		return;
+	}
+
+	if (contentElement.dataset.monsterOverflowMode === "visible") {
+		return;
+	}
+
+	const reservedHeight = getReservedFloatingHeight(
+		floatingElement,
+		contentElement,
+	);
+	const contentMaxHeight = clampAvailableDimension(
+		Number.isFinite(maxHeight) ? maxHeight - reservedHeight : null,
+		readMaxDimension(contentElement, "maxHeight"),
 	);
+
+	if (Number.isFinite(contentMaxHeight) && contentMaxHeight > 0) {
+		contentElement.style.maxHeight = `${contentMaxHeight}px`;
+	} else {
+		contentElement.style.maxHeight = "";
+	}
+
+	syncNestedScrollContainerHeight(contentElement, contentMaxHeight);
+}
+
+function getFloatingContentElement(floatingElement) {
+	for (const child of floatingElement.children) {
+		if (!(child instanceof HTMLElement)) {
+			continue;
+		}
+
+		const part = child.getAttribute("part");
+		if (
+			isString(part) &&
+			part
+				.split(/\s+/)
+				.filter((token) => token.length > 0)
+				.includes("content")
+		) {
+			return child;
+		}
+	}
+
+	return null;
+}
+
+function getReservedFloatingHeight(floatingElement, contentElement) {
+	const floatingStyle = getComputedStyle(floatingElement);
+	let reservedHeight = 0;
+
+	reservedHeight += readBoxDimension(floatingStyle.paddingTop);
+	reservedHeight += readBoxDimension(floatingStyle.paddingBottom);
+	reservedHeight += readBoxDimension(floatingStyle.borderTopWidth);
+	reservedHeight += readBoxDimension(floatingStyle.borderBottomWidth);
+
+	for (const child of floatingElement.children) {
+		if (!(child instanceof HTMLElement) || child === contentElement) {
+			continue;
+		}
+
+		const childStyle = getComputedStyle(child);
+		reservedHeight += child.getBoundingClientRect().height;
+		reservedHeight += readBoxDimension(childStyle.marginTop);
+		reservedHeight += readBoxDimension(childStyle.marginBottom);
+	}
+
+	return Math.max(0, reservedHeight);
+}
+
+function readBoxDimension(rawValue) {
+	const value = Number.parseFloat(rawValue);
+	return Number.isFinite(value) ? value : 0;
+}
+
+function syncNestedScrollContainerHeight(contentElement, contentMaxHeight) {
+	const nestedScrollableElement = getNestedScrollableElement(contentElement);
+	if (!(nestedScrollableElement instanceof HTMLElement)) {
+		return;
+	}
+
+	if (Number.isFinite(contentMaxHeight) && contentMaxHeight > 0) {
+		nestedScrollableElement.style.height = `${contentMaxHeight}px`;
+		nestedScrollableElement.style.maxHeight = `${contentMaxHeight}px`;
+		return;
+	}
+
+	nestedScrollableElement.style.height = "";
+	nestedScrollableElement.style.maxHeight = "";
+}
+
+function syncPreferredFloatingWidth(floatingElement, maxWidth) {
+	const preferredWidth = Number.parseFloat(
+		floatingElement.dataset.monsterPreferredWidth || "",
+	);
+	if (!Number.isFinite(preferredWidth) || preferredWidth <= 0) {
+		return;
+	}
+
+	const contentElement = getFloatingContentElement(floatingElement);
+	if (!(contentElement instanceof HTMLElement)) {
+		floatingElement.style.width = `${preferredWidth}px`;
+		return;
+	}
+
+	const floatingRect = floatingElement.getBoundingClientRect();
+	const contentRect = contentElement.getBoundingClientRect();
+	const reservedWidth = Math.max(0, floatingRect.width - contentRect.width);
+	const contentRequiredWidth = getRequiredContentWidth(contentElement);
+	const preferredFloatingWidth = preferredWidth;
+	const requiredFloatingWidth = Math.max(
+		preferredFloatingWidth,
+		contentRequiredWidth + reservedWidth,
+	);
+	const nextFloatingWidth = clampAvailableDimension(
+		requiredFloatingWidth,
+		Number.isFinite(maxWidth) ? maxWidth : Infinity,
+	);
+
+	if (Number.isFinite(nextFloatingWidth) && nextFloatingWidth > 0) {
+		floatingElement.style.width = `${nextFloatingWidth}px`;
+	}
+}
+
+function syncPreferredFloatingMaxWidth(floatingElement, maxWidth) {
+	const preferredMaxWidth = Number.parseFloat(
+		floatingElement.dataset.monsterPreferredMaxWidth || "",
+	);
+	if (!Number.isFinite(preferredMaxWidth) || preferredMaxWidth <= 0) {
+		return;
+	}
+
+	const nextFloatingMaxWidth = clampAvailableDimension(
+		preferredMaxWidth,
+		Number.isFinite(maxWidth) ? maxWidth : Infinity,
+	);
+	if (Number.isFinite(nextFloatingMaxWidth) && nextFloatingMaxWidth > 0) {
+		floatingElement.style.maxWidth = `${nextFloatingMaxWidth}px`;
+	}
+}
+
+function resetAdaptiveFloatingElementSize(floatingElement) {
+	if (!(floatingElement instanceof HTMLElement)) {
+		return;
+	}
+
+	floatingElement.style.removeProperty("maxHeight");
+
+	const contentElement = getFloatingContentElement(floatingElement);
+	if (!(contentElement instanceof HTMLElement)) {
+		return;
+	}
+
+	contentElement.style.removeProperty("maxHeight");
+
+	const nestedScrollableElement = getNestedScrollableElement(contentElement);
+	if (!(nestedScrollableElement instanceof HTMLElement)) {
+		return;
+	}
+
+	nestedScrollableElement.style.removeProperty("height");
+	nestedScrollableElement.style.removeProperty("maxHeight");
+}
+
+function runFloatingUpdateHook(popperElement) {
+	const hook = popperElement?.monsterBeforeFloatingUpdate;
+	if (typeof hook === "function") {
+		hook();
+	}
+}
+
+function getRequiredContentWidth(contentElement) {
+	const nestedScrollableElement = getNestedScrollableElement(contentElement);
+	if (nestedScrollableElement instanceof HTMLElement) {
+		return Math.max(
+			contentElement.scrollWidth,
+			nestedScrollableElement.scrollWidth,
+			contentElement.clientWidth,
+		);
+	}
+
+	return Math.max(contentElement.scrollWidth, contentElement.clientWidth);
+}
+
+function getNestedScrollableElement(contentElement) {
+	for (const child of contentElement.children) {
+		if (!(child instanceof HTMLElement)) {
+			continue;
+		}
+
+		const style = getComputedStyle(child);
+		if (["auto", "scroll"].includes(style.overflowY)) {
+			return child;
+		}
+	}
+
+	return null;
 }
 
 function buildDetectOverflowOptions(boundaryElement) {
@@ -418,6 +654,8 @@ function startAutoUpdate(controlElement, popperElement, callback) {
 }
 
 function stopAutoUpdate(popperElement) {
+	cancelSettlingPass(popperElement);
+	stopFloatingResizeObserver(popperElement);
 	const cleanup = autoUpdateCleanupMap.get(popperElement);
 	if (typeof cleanup === "function") {
 		cleanup();
@@ -425,6 +663,47 @@ function stopAutoUpdate(popperElement) {
 	autoUpdateCleanupMap.delete(popperElement);
 }
 
+function startFloatingResizeObserver(controlElement, popperElement, config) {
+	stopFloatingResizeObserver(popperElement);
+
+	const observer = new ResizeObserver(() => {
+		scheduleSettlingPass(controlElement, popperElement, config);
+	});
+
+	observer.observe(popperElement);
+	floatingResizeObserverMap.set(popperElement, observer);
+}
+
+function stopFloatingResizeObserver(popperElement) {
+	const observer = floatingResizeObserverMap.get(popperElement);
+	if (observer instanceof ResizeObserver) {
+		observer.disconnect();
+	}
+	floatingResizeObserverMap.delete(popperElement);
+}
+
+function scheduleSettlingPass(controlElement, popperElement, config) {
+	if (settlingFrameMap.has(popperElement)) {
+		return;
+	}
+
+	const frameId = requestAnimationFrame(() => {
+		settlingFrameMap.delete(popperElement);
+		runFloatingUpdateHook(popperElement);
+		syncFloatingPopover(controlElement, popperElement, config, false);
+	});
+
+	settlingFrameMap.set(popperElement, frameId);
+}
+
+function cancelSettlingPass(popperElement) {
+	const frameId = settlingFrameMap.get(popperElement);
+	if (typeof frameId === "number") {
+		cancelAnimationFrame(frameId);
+	}
+	settlingFrameMap.delete(popperElement);
+}
+
 function applyFloatingArrowStyles(arrowElement, placement, arrowData) {
 	if (!(arrowElement instanceof HTMLElement)) {
 		return;

package/source/data/datasource/server/restapi.mjs

@@ -35,11 +35,17 @@ const rawDataSymbol = Symbol.for(
 /**
  * The RestAPI is a class that enables a REST API server.
  *
+ * @fragments /fragments/libraries/data/datasource/server/restapi/
+ *
  * @externalExample ../../../../example/data/datasource/server/restapi.mjs
+ * @example /examples/libraries/data/datasource/server/restapi/simple/ Configure read and write endpoints
+ * @example /examples/libraries/data/datasource/server/restapi/response-callback/ Replace the default read callback with a custom assignment flow
+ * @example /examples/libraries/data/datasource/server/restapi/partial-write/ Patch only changed fields before sending a write request
+ * @example /examples/libraries/data/datasource/server/restapi/report-path/ Read validation reports from a nested response path
  * @license AGPLv3
  * @since 1.22.0
  * @copyright Volker Schukai
- * @summary The RestAPI is a class that binds a REST API server.
+ * @summary A REST-backed datasource for reading and writing application state over HTTP.
  */
 class RestAPI extends Server {
 	/**

package/source/data/datasource/server/webconnect.mjs

@@ -31,11 +31,17 @@ const webConnectSymbol = Symbol("connection");
 /**
  * The RestAPI is a class that enables a REST API server.
  *
+ * @fragments /fragments/libraries/data/datasource/server/webconnect/
+ *
  * @externalExample ../../../../example/data/datasource/server/webconnect.mjs
+ * @example /examples/libraries/data/datasource/server/webconnect/simple/ Configure a realtime datasource bridge
+ * @example /examples/libraries/data/datasource/server/webconnect/message-queue/ Read queued realtime messages through the datasource API
+ * @example /examples/libraries/data/datasource/server/webconnect/transformed-read/ Apply read mapping to incoming socket payloads
+ * @example /examples/libraries/data/datasource/server/webconnect/write-envelope/ Prepare outgoing socket writes with sheathing options
  * @license AGPLv3
  * @since 3.1.0
  * @copyright Volker Schukai
- * @summary The LocalStorage class encapsulates the access to data objects.
+ * @summary A realtime datasource that bridges WebConnect messages into the datasource API.
  */
 class WebConnect extends Server {
 	/**

package/source/data/datasource/server.mjs

@@ -30,10 +30,16 @@ const serverVersionSymbol = Symbol("serverVersion");
 /**
  * Base class for all server data sources
  *
+ * @fragments /fragments/libraries/data/datasource/server/
+ *
+ * @example /examples/libraries/data/datasource/server/simple/ Transform and prepare server payloads
+ * @example /examples/libraries/data/datasource/server/transformer-callbacks/ Combine transformer expressions with mapping callbacks
+ * @example /examples/libraries/data/datasource/server/partial-diff/ Reduce write payloads through the partial diff callback
+ * @example /examples/libraries/data/datasource/server/sheathing-object/ Wrap outgoing payloads into a server-side envelope
  * @license AGPLv3
  * @since 3.4.0
  * @copyright Volker Schukai
- * @summary The Server class encapsulates the access to a server datasource
+ * @summary A base datasource layer for reading, transforming and writing structured server payloads.
  */
 class Server extends Datasource {
 	/**

package/source/data/datasource/storage.mjs

@@ -29,6 +29,12 @@ const storageObjectSymbol = Symbol.for(
 /**
  * The class represents a record.
  *
+ * @fragments /fragments/libraries/data/datasource/storage/
+ *
+ * @example /examples/libraries/data/datasource/storage/simple/ Read and write JSON through Web Storage
+ * @example /examples/libraries/data/datasource/storage/session-draft/ Persist draft state in session storage
+ * @example /examples/libraries/data/datasource/storage/local-preferences/ Persist user preferences in local storage
+ * @example /examples/libraries/data/datasource/storage/remove-on-undefined/ Remove the storage entry when the datasource becomes undefined
  * @license AGPLv3
  * @since 1.22.0
  * @copyright Volker Schukai

package/source/data/datasource.mjs

@@ -48,6 +48,12 @@ const internalDataSymbol = Symbol.for(
  * The datasource class is the basis for dealing with different data sources.
  * It provides a unified interface for accessing data
  * @externalExample ../../example/data/datasource.mjs
+ * @fragments /fragments/libraries/data/datasource/
+ * @example /examples/libraries/data/datasource/basic-read-write/ Implement a small in memory datasource with read and write
+ * @example /examples/libraries/data/datasource/observer-log/ Attach observers and react to subject changes
+ * @example /examples/libraries/data/datasource/skip-noop-events/ Compare skipNoopEvents with repeated writes
+ * @example /examples/libraries/data/datasource/render-list/ Drive a small UI list from datasource updates
+ * @example /examples/libraries/data/datasource/async-options/ Use datasource options to control async reads
  * @license AGPLv3
  * @since 1.22.0
  * @copyright Volker Schukai

package/source/dom/assembler.mjs

@@ -29,6 +29,9 @@ const ATTRIBUTEPREFIX = "data-monster-";
 /**
  * Assembler class
  *
+ * @fragments /fragments/libraries/dom/assembler/
+ *
+ * @example /examples/libraries/dom/assembler/simple/ Basic assembly flow
  * @license AGPLv3
  * @since 1.6.0
  * @copyright Volker Schukai

package/source/dom/customcontrol.mjs

@@ -50,6 +50,11 @@ const attachedInternalSymbol = Symbol("attachedInternal");
  * Read the HTML specification for Custom Element Reactions: {@link https://html.spec.whatwg.org/dev/custom-elements.html#custom-element-reactions|Custom Element Reactions}.
  *
  * @fragments /fragments/libraries/dom/customcontrol/
+ * @example /examples/libraries/dom/customcontrol/text-input/ Build a minimal form associated text control
+ * @example /examples/libraries/dom/customcontrol/validation/ Add validation and reportValidity behaviour
+ * @example /examples/libraries/dom/customcontrol/formdata-submit/ Submit structured FormData from a custom control
+ * @example /examples/libraries/dom/customcontrol/reset-behaviour/ Restore the control state on form reset
+ * @example /examples/libraries/dom/customcontrol/disabled-sync/ Sync disabled state from form containers into the control
  *
  * @summary A form-oriented base class for Monster controls with value handling, validation and control semantics.
  * @license AGPLv3

package/source/dom/customelement.mjs

@@ -190,6 +190,11 @@ let hostVisibilityStyleSheet = null;
  * And in the [HTML Standard](https://html.spec.whatwg.org/multipage/custom-elements.html#custom-elements) or in the [WHATWG Wiki](https://wiki.whatwg.org/wiki/Custom_Elements).
  *
  * @fragments /fragments/libraries/dom/customelement/
+ * @example /examples/libraries/dom/customelement/simple-card/ Register a minimal element with inline template and stylesheet
+ * @example /examples/libraries/dom/customelement/options-from-attributes/ Read declarative options from data-monster-options
+ * @example /examples/libraries/dom/customelement/runtime-option-updates/ Update component state via setOption and setOptions
+ * @example /examples/libraries/dom/customelement/document-template/ Resolve the template from the surrounding document
+ * @example /examples/libraries/dom/customelement/visibility-events/ React to show hide and visibility events
  *
  * @license AGPLv3
  * @since 1.7.0

package/source/dom/focusmanager.mjs

@@ -42,6 +42,9 @@ const stackSymbol = Symbol("stack");
 /**
  * With the focus manager the focus can be stored in a document, recalled and moved.
  *
+ * @fragments /fragments/libraries/dom/focusmanager/
+ *
+ * @example /examples/libraries/dom/focusmanager/simple/ Store and restore focus inside a dialog flow
  * @license AGPLv3
  * @since 1.25.0
  * @copyright Volker Schukai

package/source/dom/resource/link/stylesheet.mjs

@@ -20,10 +20,13 @@ export { Stylesheet };
 /**
  * This class is used by the resource manager to embed external resources.
  *
+ * @fragments /fragments/libraries/dom/resource/link/stylesheet/
+ *
+ * @example /examples/libraries/dom/resource/link/stylesheet/simple/ Configure a stylesheet resource
  * @license AGPLv3
  * @since 1.25.0
  * @copyright Volker Schukai
- * @summary A Resource class
+ * @summary A link resource specialized for loading external stylesheets.
  * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link
  */
 class Stylesheet extends Link {

package/source/dom/resource/link.mjs

@@ -30,10 +30,13 @@ export { Link };
 /**
  * This class is used by the resource manager to embed external resources.
  *
+ * @fragments /fragments/libraries/dom/resource/link/
+ *
+ * @example /examples/libraries/dom/resource/link/simple/ Create and connect a link resource
  * @license AGPLv3
  * @since 1.25.0
  * @copyright Volker Schukai
- * @summary A Resource class
+ * @summary A link resource for attaching external link-based assets such as stylesheets or preloads.
  * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link
  */
 class Link extends Resource {

package/source/dom/resource/script.mjs

@@ -29,10 +29,13 @@ export { Script };
 /**
  * This class is used by the resource manager to embed scripts.
  *
+ * @fragments /fragments/libraries/dom/resource/script/
+ *
+ * @example /examples/libraries/dom/resource/script/simple/ Create and connect a script resource
  * @license AGPLv3
  * @since 1.25.0
  * @copyright Volker Schukai
- * @summary A Resource class
+ * @summary A script resource for inserting external JavaScript files into the document.
  */
 class Script extends Resource {
 	/**

package/source/dom/resource.mjs

@@ -56,10 +56,13 @@ const referenceSymbol = Symbol("reference");
 /**
  * This class is the base class for all resources to be loaded.
  *
+ * @fragments /fragments/libraries/dom/resource/
+ *
+ * @example /examples/libraries/dom/resource/simple/ Create and connect a DOM resource
  * @license AGPLv3
  * @since 1.25.0
  * @copyright Volker Schukai
- * @summary A Resource class
+ * @summary A base resource abstraction for creating, connecting and observing DOM-loaded assets.
  */
 class Resource extends BaseWithOptions {
 	/**

package/source/dom/resourcemanager.mjs

@@ -28,10 +28,16 @@ export { ResourceManager };
 /**
  * The ResourceManager is a singleton that manages all resources.
  *
+ * @fragments /fragments/libraries/dom/resourcemanager/
+ *
+ * @example /examples/libraries/dom/resourcemanager/simple/ Register and connect multiple resources
+ * @example /examples/libraries/dom/resourcemanager/data-url-bundle/ Connect script stylesheet and data resources from inline urls
+ * @example /examples/libraries/dom/resourcemanager/separate-registration/ Register resources in separate steps and inspect the internal groups
+ * @example /examples/libraries/dom/resourcemanager/availability-check/ Wait for registered resources to report availability
  * @license AGPLv3
  * @since 1.25.0
  * @copyright Volker Schukai
- * @summary A Resource class
+ * @summary A resource coordinator for registering and connecting scripts, stylesheets and data assets.
  */
 class ResourceManager extends Base {
 	/**

package/source/dom/template.mjs

@@ -25,6 +25,12 @@ export { Template };
 /**
  * The template class provides methods for creating templates.
  *
+ * @fragments /fragments/libraries/dom/template/
+ *
+ * @example /examples/libraries/dom/template/simple/ Clone a named template fragment
+ * @example /examples/libraries/dom/template/theme-specific/ Resolve theme specific templates by id suffix
+ * @example /examples/libraries/dom/template/prefixed-lookup/ Resolve prefixed templates near the current node
+ * @example /examples/libraries/dom/template/repeated-clones/ Clone the same template multiple times without mutating the source
  * @license AGPLv3
  * @since 1.6.0
  * @copyright Volker Schukai

package/source/dom/updater.mjs

@@ -105,6 +105,15 @@ const queuedSnapshotSymbol = Symbol("queuedSnapshot");
  * @fragments /fragments/libraries/dom/updater/
  *
  * @example /examples/libraries/dom/updater/simple/ Simple example
+ * @example /examples/libraries/dom/updater/properties-and-patch/ Properties, patching and keyed list rendering
+ * @example /examples/libraries/dom/updater/attributes-and-aria/ Attribute and ARIA mapping
+ * @example /examples/libraries/dom/updater/bind-types/ Bound value casting
+ * @example /examples/libraries/dom/updater/retrieve-once/ One-time retrieval without live events
+ * @example /examples/libraries/dom/updater/insert-template-list/ Template insertion for iterable data
+ * @example /examples/libraries/dom/updater/custom-callbacks/ Custom pipe callbacks
+ * @example /examples/libraries/dom/updater/batch-updates/ Batched update processing
+ * @example /examples/libraries/dom/updater/control-properties/ Property updates on native controls
+ * @example /examples/libraries/dom/updater/select-multiple-array/ Multi-select array binding
  *
  * @license AGPLv3
  * @since 1.8.0

package/source/i18n/formatter.mjs

@@ -31,6 +31,9 @@ const internalTranslationSymbol = Symbol("internalTranslation");
  * The Formatter extends the Text.Formatter with the possibility to replace the key by a translation.
  *
  * @fragments /fragments/libraries/i18n/formatter/
+ * @example /examples/libraries/i18n/formatter/basic-translation/ Resolve one translation key through the i18n marker
+ * @example /examples/libraries/i18n/formatter/parameterized-text/ Combine translated text with formatter parameters
+ * @example /examples/libraries/i18n/formatter/custom-markers/ Configure custom formatter markers for translated strings
  *
  * @license AGPLv3
  * @since 1.26.0

package/source/i18n/provider.mjs

@@ -38,6 +38,12 @@ const translationsLinkSymbol = Symbol.for(
 /**
  * A provider makes a translation object available.
  *
+ * @fragments /fragments/libraries/i18n/provider/
+ *
+ * @example /examples/libraries/i18n/provider/simple/ Assign translations to a document
+ * @example /examples/libraries/i18n/provider/merge-existing/ Merge a second translation payload into an already linked element
+ * @example /examples/libraries/i18n/provider/subtree-assignment/ Attach translations to a dedicated subtree instead of the whole document
+ * @example /examples/libraries/i18n/provider/locale-switch/ Resolve different translation objects for different locales
  * @license AGPLv3
  * @since 1.13.0
  * @copyright Volker Schukai

package/source/i18n/translations.mjs

@@ -36,6 +36,10 @@ export { Translations, getDocumentTranslations };
  * @fragments /fragments/libraries/i18n/translations/
  *
  * @externalExample ../../example/i18n/translations.mjs
+ * @example /examples/libraries/i18n/translations/simple/ Resolve singular and plural translations
+ * @example /examples/libraries/i18n/translations/bulk-assignment/ Load multiple translation keys from plain objects
+ * @example /examples/libraries/i18n/translations/fallbacks/ Use explicit default text when a key is missing
+ * @example /examples/libraries/i18n/translations/plural-keywords/ Resolve plural texts with explicit plural rule keywords
  * @license AGPLv3
  * @since 1.13.0
  * @copyright Volker Schukai

package/source/logging/handler.mjs

@@ -22,6 +22,12 @@ export { Handler };
 /**
  * The log handler is the interface between the log entries and the log listeners.
  *
+ * @fragments /fragments/libraries/logging/handler/
+ *
+ * @example /examples/libraries/logging/handler/simple/ Filter log entries before forwarding them
+ * @example /examples/libraries/logging/handler/level-switch/ Switch handler thresholds with the convenience methods
+ * @example /examples/libraries/logging/handler/structured-output/ Forward structured log entry data into a custom buffer
+ * @example /examples/libraries/logging/handler/off-state/ Disable a handler completely with the off level
  * @license AGPLv3
  * @since 1.5.0
  * @copyright Volker Schukai

package/source/logging/logger.mjs

@@ -68,6 +68,12 @@ const OFF = 0;
 /**
  * The logger is a class that takes care of logging.
  *
+ * @fragments /fragments/libraries/logging/logger/
+ *
+ * @example /examples/libraries/logging/logger/simple/ Write entries through a console handler
+ * @example /examples/libraries/logging/logger/multiple-handlers/ Route the same log entry through multiple handlers
+ * @example /examples/libraries/logging/logger/level-filtering/ Filter log output through handler log levels
+ * @example /examples/libraries/logging/logger/remove-handler/ Remove a handler and verify that it no longer receives entries
  * @license AGPLv3
  * @since 1.5.0
  * @copyright Volker Schukai

package/source/net/webconnect/message.mjs

@@ -22,6 +22,12 @@ const dataSymbol = Symbol("@@data");
 /**
  * This class represents a WebSocket message.
  *
+ * @fragments /fragments/libraries/net/webconnect/message/
+ *
+ * @example /examples/libraries/net/webconnect/message/simple/ Serialize and restore a structured message
+ * @example /examples/libraries/net/webconnect/message/nested-payload/ Keep nested payload data intact through serialization
+ * @example /examples/libraries/net/webconnect/message/queue-ready-shape/ Use a message shape that is ready for queue inspection and logging
+ * @example /examples/libraries/net/webconnect/message/object-access/ Access raw message data through getData and toJSON
  * @license AGPLv3
  * @since 3.4.0
  * @copyright Volker Schukai

package/source/net/webconnect.mjs

@@ -209,7 +209,13 @@ function connectServer(resolve, reject) {
 /**
  * The RestAPI is a class that enables a REST API server.
  *
+ * @fragments /fragments/libraries/net/webconnect/
+ *
  * @externalExample ../../example/net/webconnect.mjs
+ * @example /examples/libraries/net/webconnect/simple/ Connect and consume structured messages
+ * @example /examples/libraries/net/webconnect/send-and-close/ Send structured messages and close the connection manually
+ * @example /examples/libraries/net/webconnect/observer-queue/ Observe incoming queue updates through the receive queue observer API
+ * @example /examples/libraries/net/webconnect/reconnect-options/ Configure reconnect and timeout options for resilient connections
  * @license AGPLv3
  * @since 3.1.0
  * @copyright Volker Schukai

package/source/types/observablequeue.mjs

@@ -23,9 +23,12 @@ export { ObservableQueue };
  *
  * `Queue.add()` and `Queue.clear()` notify all observers.
  *
+ * @fragments /fragments/libraries/types/observablequeue/
+ *
+ * @example /examples/libraries/types/observablequeue/simple/ Observe queue changes while items are added
  * @since 3.3.0
  * @copyright Volker Schukai
- * @summary An observable Queue (Fifo)
+ * @summary A FIFO queue that notifies observers whenever its contents change.
  */
 class ObservableQueue extends Queue {
 	/**

package/source/types/observer.mjs

@@ -40,8 +40,12 @@ export { Observer };
  * observer.update(mySubject);
  * greeter.update(mySubject);
  *
+ * @fragments /fragments/libraries/types/observer/
+ *
+ * @example /examples/libraries/types/observer/simple/ Schedule a deduplicated observer update
  * @license AGPLv3
  * @since 1.0.0
+ * @summary An asynchronous observer that batches updates per subject and callback.
  */
 class Observer extends Base {
 	/**

package/test/cases/components/form/floating-ui.mjs

@@ -4,6 +4,7 @@ import { initJSDOM } from "../../../util/jsdom.mjs";
 let expect = chai.expect;
 
 let resolveClippingBoundaryElement;
+let applyAdaptiveFloatingElementSize;
 
 describe("form floating-ui boundary resolution", function () {
 	before(function (done) {
@@ -15,6 +16,7 @@ describe("form floating-ui boundary resolution", function () {
 			})
 			.then((m) => {
 				resolveClippingBoundaryElement = m.resolveClippingBoundaryElement;
+				applyAdaptiveFloatingElementSize = m.applyAdaptiveFloatingElementSize;
 				done();
 			})
 			.catch((e) => done(e));
@@ -58,4 +60,79 @@ describe("form floating-ui boundary resolution", function () {
 
 		expect(resolveClippingBoundaryElement(control, popper)).to.equal(wrapper);
 	});
+
+	it("should adapt the content max height to the available popper height", function () {
+		const mocks = document.getElementById("mocks");
+		const popper = document.createElement("div");
+		const header = document.createElement("div");
+		const content = document.createElement("div");
+		const footer = document.createElement("div");
+
+		popper.style.maxHeight = "300px";
+		content.style.maxHeight = "240px";
+		content.setAttribute("part", "content");
+
+		popper.appendChild(header);
+		popper.appendChild(content);
+		popper.appendChild(footer);
+		mocks.appendChild(popper);
+
+		header.getBoundingClientRect = () => {
+			return {
+				width: 180,
+				height: 30,
+				top: 0,
+				left: 0,
+				right: 180,
+				bottom: 30,
+				x: 0,
+				y: 0,
+			};
+		};
+		popper.getBoundingClientRect = () => {
+			return {
+				width: 220,
+				height: 200,
+				top: 0,
+				left: 0,
+				right: 220,
+				bottom: 200,
+				x: 0,
+				y: 0,
+			};
+		};
+		footer.getBoundingClientRect = () => {
+			return {
+				width: 180,
+				height: 30,
+				top: 0,
+				left: 0,
+				right: 180,
+				bottom: 30,
+				x: 0,
+				y: 0,
+			};
+		};
+		content.getBoundingClientRect = () => {
+			return {
+				width: 180,
+				height: 140,
+				top: 0,
+				left: 0,
+				right: 180,
+				bottom: 140,
+				x: 0,
+				y: 0,
+			};
+		};
+
+		applyAdaptiveFloatingElementSize(popper, {
+			availableWidth: 220,
+			availableHeight: 160,
+		});
+
+		expect(popper.style.maxHeight).to.equal("160px");
+		expect(content.style.maxWidth).to.equal("");
+		expect(content.style.maxHeight).to.equal("100px");
+	});
 });