@schukai/monster 4.154.12 → 5.0.0

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 
 
+## [5.0.0] - 2026-10-10
+
+
+
 ## [4.154.12] - 2026-10-10
 
 ### Bug Fixes

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.","exports":{".":"./source/monster.mjs","./CHANGELOG.md":"./CHANGELOG.md","./LICENSE":"./LICENSE","./README.md":"./README.md","./package.json":"./package.json","./source/*":"./source/*","./test/*":"./test/*"},"files":["source","test/cases","test/util","CHANGELOG.md"],"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"},"sideEffects":["./source/monster.mjs","./source/components/**","./source/i18n/**","./test/**"],"type":"module","version":"4.154.12"}
+{"author":"Volker Schukai","dependencies":{"@floating-ui/dom":"^1.7.6"},"description":"Monster is a simple library for creating fast, robust and lightweight websites.","exports":{".":"./source/monster.mjs","./CHANGELOG.md":"./CHANGELOG.md","./LICENSE":"./LICENSE","./README.md":"./README.md","./package.json":"./package.json","./source/*":"./source/*","./test/*":"./test/*"},"files":["source","test/cases","test/util","CHANGELOG.md"],"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"},"sideEffects":["./source/monster.mjs","./source/components/**","./source/i18n/**","./test/**"],"type":"module","version":"5.0.0"}

package/source/dom/customelement.mjs

@@ -61,6 +61,7 @@ import { addErrorAttribute } from "./error.mjs";
 
 export {
 	CustomElement,
+	OptionsNotInitializedError,
 	initMethodSymbol,
 	assembleMethodSymbol,
 	attributeObserverSymbol,
@@ -69,6 +70,34 @@ export {
 	updaterTransformerMethodsSymbol,
 };
 
+/**
+ * An options API was used before the element's option observer was created.
+ * @summary Reports an option access before CustomElement initialization.
+ * @since 5.0.0
+ */
+class OptionsNotInitializedError extends Error {
+	/**
+	 * @param {string} method attempted options API method
+	 * @param {string} component component constructor name
+	 */
+	constructor(method, component) {
+		super(
+			`${component}.${method}() requires initialized options. Do not use the options API while defaults or customization are being evaluated during construction. Use initMethodSymbol for initial options, or assembly for attribute/script configuration.`,
+		);
+		this.name = "OptionsNotInitializedError";
+		this.method = method;
+		this.component = component;
+	}
+}
+
+function requireOptionObserver(element, method) {
+	const observer = element[internalSymbol];
+	if (observer === undefined) {
+		throw new OptionsNotInitializedError(method, element.constructor.name);
+	}
+	return observer;
+}
+
 /**
  * @type {symbol}
  */
@@ -224,12 +253,15 @@ class RevisionObserver extends Observer {
  */
 class CustomElement extends HTMLElement {
 	/**
-	 * A new object is created. First, the `initOptions` method is called. Here the
-	 * options can be defined in derived classes. Subsequently, the shadowRoot is initialized.
+	 * Initializes defaults, available option attributes and customization before
+	 * creating the option observer and calling initMethodSymbol. The options API
+	 * must not be called while defaults or customization are being evaluated.
+	 * JSON/script options and DOM rendering are handled later by base assembly.
 	 *
 	 * IMPORTANT: CustomControls instances are not created via the constructor, but either via a tag in the HTML or via <code>document.createElement()</code>.
 	 *
 	 * @throws {Error} the option attribute does not contain a valid JSON definition.
+	 * @throws {OptionsNotInitializedError} an options API was called too early
 	 */
 	constructor() {
 		super();
@@ -247,9 +279,10 @@ class CustomElement extends HTMLElement {
 			);
 		}
 
-		if (this.customization instanceof Map) {
+		const customization = this.customization;
+		if (customization instanceof Map) {
 			const pathfinder = new Pathfinder(options);
-			this.customization.forEach((value, key) => {
+			customization.forEach((value, key) => {
 				if (key === undefined || key === null || key === "") {
 					return;
 				}
@@ -333,6 +366,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.
+	 * Evaluated once during construction, before the options API is available.
 	 * @return {Map}
 	 */
 	get customization() {
@@ -540,20 +574,17 @@ class CustomElement extends HTMLElement {
 	/**
 	 * nested options can be specified by path `a.b.c`
 	 *
-	 * Before the constructor has initialized the option observer, this method
-	 * returns the supplied default value. This preserves option reads from
-	 * derived `defaults` and `customization` getters during initialization.
+	 * Options are available from initMethodSymbol onwards. Attribute/script JSON
+	 * is applied during assembly. The fallback only applies to initialized options.
 	 *
 	 * @param {string} path
 	 * @param {*} defaultValue
 	 * @return {*}
+	 * @throws {OptionsNotInitializedError} options have not been initialized
 	 * @since 1.10.0
 	 */
 	getOption(path, defaultValue = undefined) {
-		const optionObserver = this[internalSymbol];
-		if (optionObserver === undefined) {
-			return defaultValue;
-		}
+		const optionObserver = requireOptionObserver(this, "getOption");
 
 		return new Pathfinder(optionObserver.getRealSubject().options).getVia(
 			path,
@@ -568,12 +599,12 @@ class CustomElement extends HTMLElement {
 	 * @param {*} value
 	 * @return {CustomElement}
 	 * @since 1.14.0
+	 * @throws {OptionsNotInitializedError} options have not been initialized
 	 */
 	setOption(path, value) {
-		new Pathfinder(this[internalSymbol].getSubject()["options"]).setVia(
-			path,
-			value,
-		);
+		new Pathfinder(
+			requireOptionObserver(this, "setOption").getSubject().options,
+		).setVia(path, value);
 		return this;
 	}
 
@@ -581,15 +612,17 @@ class CustomElement extends HTMLElement {
 	 * @since 1.15.0
 	 * @param {string|object} options
 	 * @return {CustomElement}
+	 * @throws {OptionsNotInitializedError} options have not been initialized
 	 */
 	setOptions(options) {
+		const optionObserver = requireOptionObserver(this, "setOptions");
 		if (isString(options)) {
 			options = parseOptionsJSON.call(this, options);
 		}
 		// 2024-01-21: remove this.defaults, otherwise it will overwrite
 		// the current settings that have already been made.
 		// https://gitlab.schukai.com/oss/libraries/javascript/monster/-/issues/136
-		extend(this[internalSymbol].getSubject()["options"], options);
+		extend(optionObserver.getSubject().options, options);
 
 		return this;
 	}

package/source/types/version.mjs

@@ -156,7 +156,7 @@ function getMonsterVersion() {
 	}
 
 	/** Managed by the release script; keep synchronized with package.json. */
-	monsterVersion = new Version("4.154.12");
+	monsterVersion = new Version("5.0.0");
 
 	return monsterVersion;
 }

package/test/cases/dom/customelement.mjs

@@ -1232,7 +1232,7 @@ describe('DOM', function () {
                 mocks.innerHTML = html1;
             })
 
-            it('should return the fallback while defaults and customization initialize options', function () {
+            it('should reject option reads while defaults initialize options (#596)', function () {
                 const htmlTAG = 'monster-testclass-early-option-576';
 
                 if (!customElements.get(htmlTAG)) {
@@ -1270,13 +1270,9 @@ describe('DOM', function () {
                     registerCustomElement(EarlyOptionComponent);
                 }
 
-                const element = document.createElement(htmlTAG);
-
-                expect(element.getOption('fromDefaults')).to.equal(
-                    'defaults-fallback',
-                );
-                expect(element.getOption('fromCustomization')).to.equal(
-                    'customization-fallback',
+                const Constructor = customElements.get(htmlTAG);
+                expect(() => new Constructor()).to.throw(
+                    'getOption() requires initialized options',
                 );
             });
 

package/test/cases/dom/early-options-contract.mjs

@@ -0,0 +1,40 @@
+import { strict as assert } from "node:assert";
+import { readFileSync } from "node:fs";
+import { globSync } from "glob";
+import { findEarlyOptions } from "../../util/early-options.mjs";
+
+describe("Early options source contract (#596)", () => {
+	it("rejects synchronous helper and method calls but allows deferred callbacks", () => {
+		const source = `
+		function helper() { return this.getOption("value"); }
+		class Example {
+			get defaults() { return { value: helper.call(this), later: () => this.getOption("later") }; }
+			get customization() { this.configure(); return new Map(); }
+			configure() { this.setOptions({}); }
+		}`;
+		assert.deepEqual(
+			findEarlyOptions(source).map(({ phase, method }) => ({ phase, method })),
+			[
+				{ phase: "defaults", method: "getOption" },
+				{ phase: "customization", method: "setOptions" },
+			],
+		);
+		assert.equal(
+			findEarlyOptions(
+				'class Example { get defaults() { return (() => this.setOption("x", 1))(); } }',
+			).length,
+			1,
+		);
+	});
+	it("has no statically resolved early options access in library getters", () => {
+		const root = new URL("../../../", import.meta.url);
+		const files = globSync("source/**/*.mjs", { cwd: root }).sort();
+		assert.ok(files.length > 300);
+		const failures = files.flatMap((file) =>
+			findEarlyOptions(readFileSync(new URL(file, root), "utf8")).map(
+				(failure) => ({ file, ...failure }),
+			),
+		);
+		assert.deepEqual(failures, []);
+	});
+});

package/test/cases/dom/options-lifecycle.mjs

@@ -0,0 +1,216 @@
+import { expect } from "chai";
+import { initJSDOM } from "../../util/jsdom.mjs";
+
+describe("Strict options lifecycle (#596)", function () {
+	let api;
+	let fixture;
+	let sequence = 0;
+	const tick = () => new Promise((resolve) => setTimeout(resolve, 30));
+
+	before(async () => {
+		await initJSDOM({});
+		api = await import("../../../source/dom/customelement.mjs");
+	});
+	beforeEach(() => {
+		fixture = document.createElement("div");
+		document.getElementById("mocks").append(fixture);
+	});
+	afterEach(() => fixture.remove());
+
+	function register(Constructor) {
+		const tag = `monster-options-596-${++sequence}`;
+		customElements.define(tag, Constructor);
+		return tag;
+	}
+
+	for (const phase of ["defaults", "customization"]) {
+		for (const [method, args] of [
+			["getOption", ["value", "fallback"]],
+			["setOption", ["value", "early"]],
+			["setOptions", [{ value: "early" }]],
+			["setOptions", ["invalid JSON"]],
+		]) {
+			it(`rejects ${method}(${JSON.stringify(args)}) in ${phase}`, () => {
+				class EarlyOptions extends api.CustomElement {}
+				Object.defineProperty(EarlyOptions.prototype, phase, {
+					get() {
+						return this[method](...args);
+					},
+				});
+				register(EarlyOptions);
+				let failure;
+				try {
+					new EarlyOptions();
+				} catch (error) {
+					failure = error;
+				}
+				expect(failure).to.be.instanceOf(api.OptionsNotInitializedError);
+				expect(failure.name).to.equal("OptionsNotInitializedError");
+				expect(failure.method).to.equal(method);
+				expect(failure.component).to.equal("EarlyOptions");
+				expect(failure.message).to.include("initMethodSymbol");
+			});
+		}
+	}
+
+	it("evaluates customization once and makes reads and writes available in init", () => {
+		let evaluations = 0;
+		class Initialized extends api.CustomElement {
+			get defaults() {
+				return { ...super.defaults, value: "default", nested: { kept: true } };
+			}
+			get customization() {
+				evaluations++;
+				return new Map([["value", "custom"]]);
+			}
+			[api.initMethodSymbol]() {
+				super[api.initMethodSymbol]();
+				expect(this.getOption("value")).to.equal("custom");
+				expect(this.setOption("nested.added", 1)).to.equal(this);
+				expect(this.setOptions('{"nested":{"other":2}}')).to.equal(this);
+			}
+		}
+		const element = document.createElement(register(Initialized));
+		expect(element).to.be.instanceOf(Initialized);
+		expect(evaluations).to.equal(1);
+		expect(element.getOption("nested")).to.deep.equal({
+			kept: true,
+			added: 1,
+			other: 2,
+		});
+	});
+
+	it("preserves fallback and falsy values, and propagates unrelated failures", () => {
+		class Options extends api.CustomElement {}
+		const element = document.createElement(register(Options));
+		for (const value of [null, false, 0, ""]) {
+			element.setOption("value", value);
+			expect(element.getOption("value", "fallback")).to.equal(value);
+		}
+		element.setOption("value", undefined);
+		expect(element.getOption("value", "fallback")).to.equal("fallback");
+		expect(element.getOption("missing.deep", "fallback")).to.equal("fallback");
+		expect(element.getOption("missing.deep")).to.equal(undefined);
+		expect(() => element.setOptions("invalid JSON")).to.throw();
+		const failure = new Error("property failure");
+		element.setOption(
+			"broken",
+			Object.defineProperty({}, "value", {
+				get() {
+					throw failure;
+				},
+				enumerable: true,
+			}),
+		);
+		expect(() => element.getOption("broken.value", "fallback")).to.throw(
+			failure,
+		);
+	});
+
+	it("preserves attribute/customization precedence on upgrade and permits deferred defaults callbacks", async () => {
+		class Upgraded extends api.CustomElement {
+			get defaults() {
+				return {
+					...super.defaults,
+					value: "default",
+					fromAttribute: "default",
+					readLater: () => this.getOption("value"),
+					templates: { main: "<span></span>" },
+				};
+			}
+			get customization() {
+				return new Map([["value", "custom"]]);
+			}
+			[api.initMethodSymbol]() {
+				super[api.initMethodSymbol]();
+				this.initialValue = this.getOption("value");
+				this.initialAttribute = this.getOption("fromAttribute");
+			}
+		}
+		const tag = `monster-options-596-${++sequence}`;
+		const holder = document.createElement("div");
+		holder.innerHTML = `<${tag} data-monster-option-value="attribute" data-monster-option-from-attribute="present"></${tag}>`;
+		const element = holder.firstElementChild;
+		customElements.define(tag, Upgraded);
+		customElements.upgrade(element);
+		expect(element).to.be.instanceOf(Upgraded);
+		expect(element.initialValue).to.equal("custom");
+		expect(element.initialAttribute).to.equal("present");
+		expect(element.getOption("readLater")()).to.equal("custom");
+		fixture.append(element);
+		await tick();
+		expect(element.getOption("readLater")()).to.equal("attribute");
+	});
+
+	it("applies late attributes, JSON and script before rendering; reconnect keeps state", async () => {
+		let assemblies = 0;
+		class Configured extends api.CustomElement {
+			get defaults() {
+				return {
+					...super.defaults,
+					value: "default",
+					flag: false,
+					count: 0,
+					templates: {
+						main: '<span data-monster-replace="path:value"></span>',
+					},
+				};
+			}
+			get customization() {
+				return new Map([["value", "custom"]]);
+			}
+			[api.initMethodSymbol]() {
+				super[api.initMethodSymbol]();
+				this.initialValue = this.getOption("value");
+			}
+			[api.assembleMethodSymbol]() {
+				assemblies++;
+				super[api.assembleMethodSymbol]();
+				this.assembledValue = this.getOption("value");
+			}
+		}
+		const element = document.createElement(register(Configured));
+		expect(element.initialValue).to.equal("custom");
+		element.setOption("value", "runtime-before-connect");
+		element.setAttribute("data-monster-option-value", "attribute");
+		element.setAttribute("data-monster-option-flag", "true");
+		element.setAttribute("data-monster-option-count", "7");
+		element.setAttribute("data-monster-options", '{"value":"json"}');
+		const script = document.createElement("script");
+		script.type = "application/json";
+		script.id = "options-script-596";
+		script.textContent = '{"value":"script"}';
+		fixture.append(script);
+		element.setAttribute(
+			"data-monster-options-selector",
+			"#options-script-596",
+		);
+		fixture.append(element);
+		await tick();
+		expect(element.assembledValue).to.equal("script");
+		expect(element.getOption("flag")).to.equal(true);
+		expect(element.getOption("count")).to.equal(7);
+		expect(element.shadowRoot.querySelector("span").textContent).to.equal(
+			"script",
+		);
+		element.removeAttribute("data-monster-option-value");
+		await tick();
+		element.setOption("value", "runtime");
+		await tick();
+		expect(element.shadowRoot.querySelector("span").textContent).to.equal(
+			"runtime",
+		);
+		element.remove();
+		script.textContent = '{"value":"must-not-reload"}';
+		fixture.append(element);
+		await tick();
+		expect(assemblies).to.equal(1);
+		expect(element.getOption("value")).to.equal("runtime");
+		element.setOption("value", "reconnected");
+		await tick();
+		expect(element.shadowRoot.querySelector("span").textContent).to.equal(
+			"reconnected",
+		);
+		expect(element.hasAttribute("data-monster-error")).to.equal(false);
+	});
+});

package/test/util/early-options.mjs

@@ -0,0 +1,84 @@
+import { parse } from "espree";
+
+const optionMethods = new Set(["getOption", "setOption", "setOptions"]);
+const functions = new Set([
+	"FunctionDeclaration",
+	"FunctionExpression",
+	"ArrowFunctionExpression",
+]);
+const children = (node) =>
+	Object.values(node)
+		.flat()
+		.filter((value) => value && typeof value.type === "string");
+const property = (node) =>
+	node.computed ? node.property?.value : node.property?.name;
+
+// A conservative local call-graph check. Imported/dynamic dispatch is covered
+// by the actual component construction tests, not claimed as statically proven.
+export function findEarlyOptions(source) {
+	const ast = parse(source, {
+		ecmaVersion: "latest",
+		sourceType: "module",
+		loc: true,
+	});
+	const helpers = new Map();
+	const getters = [];
+	function collect(node, methods = new Map()) {
+		if (node.type === "ClassBody") {
+			methods = new Map(
+				node.body
+					.filter((entry) => !entry.computed && entry.value)
+					.map((entry) => [entry.key.name, entry.value]),
+			);
+		}
+		if (node.type === "FunctionDeclaration" && node.id)
+			helpers.set(node.id.name, node);
+		if (node.type === "VariableDeclarator" && functions.has(node.init?.type))
+			helpers.set(node.id.name, node.init);
+		if (
+			node.type === "MethodDefinition" &&
+			node.kind === "get" &&
+			["defaults", "customization"].includes(node.key.name)
+		) {
+			getters.push({ node, methods });
+		}
+		for (const child of children(node)) collect(child, methods);
+	}
+	collect(ast);
+	const failures = [];
+	for (const { node: getter, methods } of getters) {
+		const visited = new Set();
+		function execute(fn) {
+			if (!fn || visited.has(fn)) return;
+			visited.add(fn);
+			walk(fn.body);
+		}
+		function walk(node) {
+			if (!node || functions.has(node.type)) return; // callbacks are deferred unless invoked
+			if (node.type === "CallExpression") {
+				let callee = node.callee;
+				if (
+					callee.type === "MemberExpression" &&
+					["call", "apply"].includes(property(callee))
+				)
+					callee = callee.object;
+				if (callee.type === "MemberExpression") {
+					const name = property(callee);
+					if (optionMethods.has(name))
+						failures.push({
+							phase: getter.key.name,
+							method: name,
+							line: node.loc.start.line,
+						});
+					if (callee.object.type === "ThisExpression")
+						execute(methods.get(name));
+				} else if (callee.type === "Identifier")
+					execute(helpers.get(callee.name));
+				else if (functions.has(callee.type)) execute(callee);
+			}
+			for (const child of children(node)) walk(child);
+		}
+		execute(getter.value);
+	}
+	return failures;
+}