@schukai/monster 4.80.0 → 4.81.0

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 
 
+## [4.81.0] - 2026-01-07
+
+### Add Features
+
+- Add new State Machine implementation and Control Flow documentation
+### Changes
+
+- update doc; close isse [#365](https://gitlab.schukai.com/oss/libraries/javascript/monster/issues/365)
+
+
+
 ## [4.80.0] - 2026-01-07
 
 ### Add Features

package/package.json

@@ -1 +1 @@
-{"author":"Volker Schukai","dependencies":{"@floating-ui/dom":"^1.7.4","@popperjs/core":"^2.11.8"},"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.80.0"}
+{"author":"Volker Schukai","dependencies":{"@floating-ui/dom":"^1.7.4","@popperjs/core":"^2.11.8"},"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.81.0"}

package/source/components/form/toggle-switch.mjs

@@ -30,7 +30,7 @@ import {
 	ATTRIBUTE_ROLE,
 } from "../../dom/constants.mjs";
 import { getWindow } from "../../dom/util.mjs";
-import { fireEvent } from "../../dom/events.mjs";
+import { fireCustomEvent, fireEvent } from "../../dom/events.mjs";
 import { addErrorAttribute } from "../../dom/error.mjs";
 
 export { ToggleSwitch };
@@ -224,6 +224,8 @@ class ToggleSwitch extends CustomControl {
 	toggleOn() {
 		this.setOption("value", this.getOption("values.on"));
 		fireEvent(this, "change");
+		fireCustomEvent(this, "monster-change", { value: this.value });
+		fireCustomEvent(this, "monster-changed", { value: this.value });
 		return this;
 	}
 
@@ -240,6 +242,8 @@ class ToggleSwitch extends CustomControl {
 	toggleOff() {
 		this.setOption("value", this.getOption("values.off"));
 		fireEvent(this, "change");
+		fireCustomEvent(this, "monster-change", { value: this.value });
+		fireCustomEvent(this, "monster-changed", { value: this.value });
 		return this;
 	}
 

package/source/dom/controlflow.mjs

@@ -0,0 +1,415 @@
+/**
+ * Copyright © Volker Schukai and all contributing authors, {{copyRightYear}}. All rights reserved.
+ * Node module: @schukai/monster
+ *
+ * This source code is licensed under the GNU Affero General Public License version 3 (AGPLv3).
+ * The full text of the license can be found at: https://www.gnu.org/licenses/agpl-3.0.en.html
+ *
+ * For those who do not wish to adhere to the AGPLv3, a commercial license is available.
+ * Acquiring a commercial license allows you to use this software without complying with the AGPLv3 terms.
+ * For more information about purchasing a commercial license, please contact Volker Schukai.
+ *
+ * SPDX-License-Identifier: AGPL-3.0
+ */
+
+import { Pathfinder } from "../data/pathfinder.mjs";
+import { ProxyObserver } from "../types/proxyobserver.mjs";
+import { Observer } from "../types/observer.mjs";
+import { isArray, isFunction, isObject, isString } from "../types/is.mjs";
+import { getDocument } from "./util.mjs";
+
+export { ControlFlow };
+
+/**
+ * Lightweight control flow for event-driven control dependencies.
+ * Config is defined in JS and supports callbacks per event.
+ */
+class ControlFlow {
+	constructor({
+		stateObserver,
+		state = {},
+		controls = {},
+		datasources = {},
+		rules = [],
+	} = {}) {
+		this[internalSymbol] = {
+			stateObserver:
+				stateObserver instanceof ProxyObserver
+					? stateObserver
+					: new ProxyObserver(state),
+			controls: resolveControls(controls),
+			datasources: resolveDatasources(datasources),
+			rules: isArray(rules) ? rules : [],
+			listeners: [],
+		};
+
+		this.state = this[internalSymbol].stateObserver.getSubject();
+
+		this[internalSymbol].stateObserver.attachObserver(
+			new Observer(() => {
+				this.emit({
+					source: "state",
+					id: "root",
+					event: "changed",
+					value: this.state,
+				});
+			}),
+		);
+
+		bindControlEvents.call(this);
+		bindDatasourceEvents.call(this);
+	}
+
+	/**
+	 * Create an API helper for rule handlers.
+	 * @return {object}
+	 */
+	createApi() {
+		return createApi(this);
+	}
+
+	/**
+	 * Add a rule at runtime.
+	 * @param {object} rule
+	 */
+	addRule(rule) {
+		if (isObject(rule)) {
+			this[internalSymbol].rules.push(rule);
+		}
+	}
+
+	/**
+	 * Remove all listeners.
+	 */
+	destroy() {
+		for (const entry of this[internalSymbol].listeners) {
+			entry.element.removeEventListener(entry.type, entry.handler);
+		}
+		this[internalSymbol].listeners = [];
+	}
+
+	/**
+	 * Emit a synthetic event into the rule system.
+	 * @param {object} ctx
+	 */
+	emit(ctx) {
+		const context = normalizeContext(ctx, this);
+		for (const rule of this[internalSymbol].rules) {
+			if (!matchRule(rule, context)) {
+				continue;
+			}
+			const run = rule?.run;
+			if (isFunction(run)) {
+				run(context, createApi(this));
+			}
+		}
+	}
+
+	/**
+	 * Rule helper: control events.
+	 * @param {string} id
+	 * @param {string|string[]} events
+	 * @param {function} run
+	 * @return {object}
+	 */
+	static onControl(id, events, run) {
+		return {
+			on: (ctx) =>
+				ctx.source === "control" &&
+				ctx.id === id &&
+				matchEvent(ctx.event, events),
+			run,
+		};
+	}
+
+	/**
+	 * Rule helper: datasource events.
+	 * @param {string} id
+	 * @param {string|string[]} events
+	 * @param {function} run
+	 * @return {object}
+	 */
+	static onDatasource(id, events, run) {
+		return {
+			on: (ctx) =>
+				ctx.source === "datasource" &&
+				ctx.id === id &&
+				matchEvent(ctx.event, events),
+			run,
+		};
+	}
+
+	/**
+	 * Rule helper: state events.
+	 * @param {string|string[]} events
+	 * @param {function} run
+	 * @return {object}
+	 */
+	static onState(events, run) {
+		return {
+			on: (ctx) =>
+				ctx.source === "state" && matchEvent(ctx.event, events),
+			run,
+		};
+	}
+
+	/**
+	 * Rule helper: custom app events.
+	 * @param {string|string[]} events
+	 * @param {function} run
+	 * @return {object}
+	 */
+	static onApp(events, run) {
+		return {
+			on: (ctx) => ctx.source === "app" && matchEvent(ctx.event, events),
+			run,
+		};
+	}
+}
+
+/**
+ * @private
+ */
+const internalSymbol = Symbol("controlFlowInternal");
+
+/**
+ * @private
+ */
+function resolveControls(controls) {
+	const resolved = {};
+	for (const [id, def] of Object.entries(controls || {})) {
+		const element = resolveElement(def?.element || def);
+		if (!element) continue;
+		resolved[id] = {
+			element,
+			events: def?.events || ["monster-changed", "change"],
+		};
+	}
+	return resolved;
+}
+
+/**
+ * @private
+ */
+function resolveDatasources(datasources) {
+	const resolved = {};
+	for (const [id, def] of Object.entries(datasources || {})) {
+		const element = resolveElement(def?.element || def);
+		if (!element) continue;
+		resolved[id] = {
+			element,
+			events: def?.events || [
+				"monster-datasource-fetched",
+				"monster-datasource-error",
+			],
+		};
+	}
+	return resolved;
+}
+
+/**
+ * @private
+ */
+function resolveElement(elementOrSelector) {
+	if (elementOrSelector instanceof HTMLElement) {
+		return elementOrSelector;
+	}
+	if (isString(elementOrSelector)) {
+		return getDocument().querySelector(elementOrSelector);
+	}
+	return null;
+}
+
+/**
+ * @private
+ */
+function bindControlEvents() {
+	for (const [id, control] of Object.entries(this[internalSymbol].controls)) {
+		for (const type of control.events) {
+			const handler = (event) => {
+				this.emit({
+					source: "control",
+					id,
+					event: type,
+					value: readControlValue(control.element),
+					rawEvent: event,
+				});
+			};
+			control.element.addEventListener(type, handler);
+			this[internalSymbol].listeners.push({
+				element: control.element,
+				type,
+				handler,
+			});
+		}
+	}
+}
+
+/**
+ * @private
+ */
+function bindDatasourceEvents() {
+	for (const [id, datasource] of Object.entries(
+		this[internalSymbol].datasources,
+	)) {
+		for (const type of datasource.events) {
+			const handler = (event) => {
+				this.emit({
+					source: "datasource",
+					id,
+					event: type,
+					value: datasource.element?.data,
+					rawEvent: event,
+				});
+			};
+			datasource.element.addEventListener(type, handler);
+			this[internalSymbol].listeners.push({
+				element: datasource.element,
+				type,
+				handler,
+			});
+		}
+	}
+}
+
+/**
+ * @private
+ */
+function readControlValue(element) {
+	if (element && "value" in element) {
+		return element.value;
+	}
+	if (isFunction(element?.getOption)) {
+		return element.getOption("value");
+	}
+	return undefined;
+}
+
+/**
+ * @private
+ */
+function matchRule(rule, ctx) {
+	if (!rule) return false;
+	if (isFunction(rule.on)) {
+		return !!rule.on(ctx);
+	}
+	if (isString(rule.on)) {
+		return rule.on === ctx.key || rule.on === ctx.topic;
+	}
+	if (isArray(rule.on)) {
+		return rule.on.includes(ctx.key) || rule.on.includes(ctx.topic);
+	}
+	return false;
+}
+
+/**
+ * @private
+ */
+function normalizeContext(ctx, flow) {
+	const context = Object.assign({}, ctx || {});
+	context.key = `${context.source}:${context.id}:${context.event}`;
+	context.topic = `${context.source}:${context.id}`;
+	context.state = flow.state;
+	context.controls = flow[internalSymbol].controls;
+	context.datasources = flow[internalSymbol].datasources;
+	return context;
+}
+
+/**
+ * @private
+ */
+function matchEvent(event, events) {
+	if (!events) return true;
+	if (isString(events)) {
+		return event === events;
+	}
+	if (isArray(events)) {
+		return events.includes(event);
+	}
+	return false;
+}
+
+/**
+ * @private
+ */
+function createApi(flow) {
+	return {
+		state: flow.state,
+		getState(path, fallback) {
+			try {
+				return new Pathfinder(flow.state).getVia(path);
+			} catch (e) {
+				return fallback;
+			}
+		},
+		setState(path, value) {
+			new Pathfinder(flow.state).setVia(path, value);
+		},
+		getControl(id) {
+			return flow[internalSymbol].controls?.[id]?.element;
+		},
+		setControlOption(id, path, value) {
+			const control = flow[internalSymbol].controls?.[id]?.element;
+			if (isFunction(control?.setOption)) {
+				control.setOption(path, value);
+			}
+		},
+		setControlOptions(id, options) {
+			const control = flow[internalSymbol].controls?.[id]?.element;
+			if (isFunction(control?.setOptions)) {
+				control.setOptions(options);
+			} else if (isFunction(control?.setOption)) {
+				control.setOption("options", options);
+			}
+		},
+		setControlValue(id, value) {
+			const control = flow[internalSymbol].controls?.[id]?.element;
+			if (control && "value" in control) {
+				control.value = value;
+			} else if (isFunction(control?.setOption)) {
+				control.setOption("value", value);
+			}
+		},
+		clearControl(id) {
+			const control = flow[internalSymbol].controls?.[id]?.element;
+			if (control && "value" in control) {
+				control.value = "";
+			} else if (isFunction(control?.setOption)) {
+				control.setOption("value", "");
+			}
+		},
+		disableControl(id, disabled) {
+			const control = flow[internalSymbol].controls?.[id]?.element;
+			if (isFunction(control?.setOption)) {
+				control.setOption("disabled", !!disabled);
+			}
+		},
+		fetchDatasource(id, { url, transform } = {}) {
+			const datasource = flow[internalSymbol].datasources?.[id]?.element;
+			if (!datasource) {
+				return Promise.reject(new Error("datasource not found"));
+			}
+			return new Promise((resolve, reject) => {
+				const onFetched = () => resolve(datasource.data);
+				const onError = (event) => {
+					reject(event?.detail?.error || new Error("Datasource error"));
+				};
+				datasource.addEventListener("monster-datasource-fetched", onFetched, {
+					once: true,
+				});
+				datasource.addEventListener("monster-datasource-error", onError, {
+					once: true,
+				});
+				if (isFunction(transform)) {
+					datasource.setOption("read.responseCallback", (payload) => {
+						datasource.data = transform(payload);
+					});
+				}
+				if (url) {
+					datasource.setOption("read.url", url);
+				}
+				datasource.read();
+			});
+		},
+	};
+}

package/source/monster.mjs

@@ -161,6 +161,7 @@ export * from "./constraints/andoperator.mjs";
 export * from "./constraints/isarray.mjs";
 export * from "./constraints/abstract.mjs";
 export * from "./constraints/valid.mjs";
+export * from "./dom/controlflow.mjs";
 export * from "./dom/dimension.mjs";
 export * from "./dom/error.mjs";
 export * from "./dom/resource/link/stylesheet.mjs";