@schukai/monster 5.0.0 → 5.0.1

package/CHANGELOG.md

@@ -2,9 +2,26 @@
 
 
 
+## [5.0.1] - 2026-10-11
+
+### Bug Fixes
+
+- **docs:** ship Monster 5 migration guide ([#597](https://gitlab.schukai.com/oss/libraries/javascript/monster/issues/597))
+
+
+
 ## [5.0.0] - 2026-10-10
 
+### Breaking Changes
 
+- **custom-element:** `getOption()`, `setOption()` and `setOptions()` now throw
+  `OptionsNotInitializedError` while `defaults` or `customization` are being
+  evaluated ([#596](https://gitlab.schukai.com/oss/libraries/javascript/monster/issues/596)).
+  Keep both getters and their helpers declarative. Use `initMethodSymbol` for
+  initialized constructor options and `assembleMethodSymbol` after late
+  attributes or script configuration have been applied. Monster 5 deliberately
+  provides no compatibility switch, early fallback or write queue. See the
+  [Monster 5 options migration guide](documentation/migrations/monster-5-options.md).
 
 ## [4.154.12] - 2026-10-10
 

package/README.md

@@ -25,6 +25,14 @@ For certain functions, additional [polyfills](#polyfill) may be required.
 
 To access our documentation and examples, visit [monsterjs.org/](https://monsterjs.org/).
 
+### Migrating to Monster 5
+
+Monster 5 makes the custom-element option lifecycle strict. Option access is
+not available while `defaults` or `customization` are being evaluated. See the
+[Monster 5 options migration guide](documentation/migrations/monster-5-options.md)
+for the lifecycle contract, migration examples and the correct use of
+`initMethodSymbol` and `assembleMethodSymbol`.
+
 ## Installation
 
 Install Monster using npm, Yarn, or pnpm:

package/documentation/migrations/monster-5-options.md

@@ -0,0 +1,90 @@
+# Monster 5: initialized options
+
+`CustomElement.getOption()`, `setOption()` and `setOptions()` require an initialized
+option observer. Calls made while the constructor evaluates `defaults` or
+`customization` throw `OptionsNotInitializedError`. The error is exported from
+`source/dom/customelement.mjs` and the main Monster entry point; its `method` and
+`component` properties identify the attempted operation and class.
+
+Monster 4.154.10 restored a fallback for early reads. Monster 5 removes that
+fallback. There is no compatibility switch, dependency injection setting or
+queue for early writes. Normal fallback values for missing initialized options
+continue to work, as do `false`, `0`, `""` and `null`.
+
+## Lifecycle
+
+1. The constructor reads `defaults`, applies available `data-monster-option-*`
+   attributes and applies `customization` (evaluated once).
+2. It creates the option observer, then calls `initMethodSymbol`. All three
+   option methods are now usable. Derived instance fields are not initialized
+   yet: this hook runs inside the base constructor.
+3. On first connection, option attributes are read again. The base assembly
+   merges `data-monster-options`, then the script selected by
+   `data-monster-options-selector`, before rendering and connecting updaters.
+4. Runtime setters notify observers. `setOptions()` merges without resetting
+   defaults. Reconnection rebinds the existing DOM and updater snapshot; it does
+   not repeat assembly or reload the JSON/script configuration.
+
+Available attributes depend on the creation path. In particular,
+`document.createElement()` cannot see attributes the caller will set later.
+An initialized API is therefore not a promise that all configuration sources
+have already been applied. Existing attribute conversion and precedence remain
+unchanged, including the attribute reread on connection.
+
+## Migration
+
+This creates a circular dependency and is no longer supported:
+
+```js
+get defaults() {
+  return { ...super.defaults, title: this.getOption("labels.title", "Details") };
+}
+```
+
+Define initial values without reading the options under construction:
+
+```js
+get defaults() {
+  return {
+    ...super.defaults,
+    labels: { title: "Details" },
+    templates: {
+      main: '<h2 data-monster-replace="path:labels.title"></h2>',
+    },
+  };
+}
+```
+
+Updater-bound markup reads the assembled configuration and follows subsequent
+changes. For imperative work that needs JSON/script options, use the existing
+assembly hook after its `super` call:
+
+```js
+[assembleMethodSymbol]() {
+  super[assembleMethodSymbol]();
+  this.configureFromResource(this.getOption("resourceConfig"));
+  return this;
+}
+```
+
+At that point the base template has already rendered. Do not move template
+configuration after rendering and expect it to rebuild automatically. Prefer a
+static template with updater bindings, or update the rendered component through
+its established API. Do not permanently cache IDs or context keys from
+constructor-time fallbacks.
+
+Work needing only constructor configuration can use `initMethodSymbol` after
+its `super` call. Callbacks stored in defaults may read options when invoked
+later; the restriction concerns execution during initialization, not where a
+callback is declared. The same rule applies to helpers called by either getter.
+
+Consumer subclasses must migrate before adopting Monster 5. Other option
+classes, including the deprecated `BaseWithOptions`, are outside this change.
+
+## Verification
+
+Issue #596 adds API lifecycle tests, a local AST call-graph check, and browser
+construction/assembly coverage for the registered component catalog. The static
+check resolves direct calls, local helpers and methods; it is not a proof about
+imported or dynamically selected functions. Browser coverage complements it.
+Existing form, updater, datatable and reconnect suites remain release gates.

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":"5.0.0"}
+{"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","./documentation/migrations/monster-5-options.md":"./documentation/migrations/monster-5-options.md","./package.json":"./package.json","./source/*":"./source/*","./test/*":"./test/*"},"files":["source","test/cases","test/util","documentation/migrations/monster-5-options.md","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.1"}

package/source/types/version.mjs

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

package/test/cases/packaging.mjs

@@ -27,6 +27,10 @@ function readBuildNix() {
 	return readFileSync(join(projectRoot, "nix/scripts/build.nix"), "utf8");
 }
 
+function readProjectFile(path) {
+	return readFileSync(join(projectRoot, path), "utf8");
+}
+
 describe("Packaging issue #577", function () {
 	describe("exports map", function () {
 		it("should resolve every literal export target to an existing file", function () {
@@ -161,6 +165,62 @@ describe("Packaging issue #577", function () {
 				).to.be.true;
 			}
 		});
+
+		it("should ship and export the Monster 5 migration guide", function () {
+			const migrationPath = "documentation/migrations/monster-5-options.md";
+			const pkg = readPackageJson();
+			const buildNix = readBuildNix();
+
+			expect(pkg.files).to.include(migrationPath);
+			expect(pkg.exports[`./${migrationPath}`]).to.equal(`./${migrationPath}`);
+			expect(existsSync(join(projectRoot, migrationPath))).to.be.true;
+			expect(buildNix).to.include(migrationPath);
+			expect(buildNix).to.include(`package/${migrationPath}`);
+		});
+	});
+
+	describe("Monster 5 migration contract", function () {
+		it("should document the strict lifecycle and migration phases", function () {
+			const guide = readProjectFile(
+				"documentation/migrations/monster-5-options.md",
+			);
+
+			for (const contract of [
+				"OptionsNotInitializedError",
+				"getOption()",
+				"setOption()",
+				"setOptions()",
+				"defaults",
+				"customization",
+				"document.createElement()",
+				"initMethodSymbol",
+				"assembleMethodSymbol",
+				"There is no compatibility switch",
+			]) {
+				expect(guide, `migration guide is missing ${contract}`).to.include(
+					contract,
+				);
+			}
+		});
+
+		it("should describe the breaking change in the 5.0.0 changelog", function () {
+			const changelog = readProjectFile("CHANGELOG.md");
+			const release = changelog
+				.split("## [5.0.0]")[1]
+				.split("## [4.154.12]")[0];
+
+			for (const contract of [
+				"### Breaking Changes",
+				"OptionsNotInitializedError",
+				"initMethodSymbol",
+				"assembleMethodSymbol",
+				"documentation/migrations/monster-5-options.md",
+			]) {
+				expect(release, `5.0.0 changelog is missing ${contract}`).to.include(
+					contract,
+				);
+			}
+		});
 	});
 
 	describe("generated barrel", function () {