@schukai/monster 5.0.0 → 5.1.0

package/CHANGELOG.md

@@ -2,9 +2,34 @@
 
 
 
+## [5.1.0] - 2026-10-11
+
+### Add Features
+
+- **style:** add composable content surfaces ([#598](https://gitlab.schukai.com/oss/libraries/javascript/monster/issues/598))
+
+
+
+## [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.1.0"}

package/source/components/style/surface.css

@@ -0,0 +1,2 @@
+/** generated from surface.pcss **/
+:where(.monster-surface){box-sizing:border-box;min-inline-size:0;display:grid;gap:var(--monster-surface-gap,var(--monster-space-3));padding:var(--monster-surface-padding,var(--monster-space-5));border-width:var(--monster-border-width);border-style:var(--monster-border-style);border-color:var(--monster-color-border-1);border-radius:var(--monster-border-radius);box-shadow:var(--monster-box-shadow-1)}.monster-surface-grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(min(100%,var(--monster-surface-grid-min-inline-size,20rem)),1fr));gap:var(--monster-surface-grid-gap,var(--monster-space-5));align-items:stretch}.monster-surface-actions{display:flex;flex-wrap:wrap;align-items:center;gap:var(--monster-surface-actions-gap,var(--monster-space-3));margin-block-start:auto}

package/source/components/style/surface.pcss

@@ -0,0 +1,33 @@
+:where(.monster-surface) {
+	box-sizing: border-box;
+	min-inline-size: 0;
+	display: grid;
+	gap: var(--monster-surface-gap, var(--monster-space-3));
+	padding: var(--monster-surface-padding, var(--monster-space-5));
+	border-width: var(--monster-border-width);
+	border-style: var(--monster-border-style);
+	border-color: var(--monster-color-border-1);
+	border-radius: var(--monster-border-radius);
+	box-shadow: var(--monster-box-shadow-1);
+}
+
+.monster-surface-grid {
+	display: grid;
+	grid-template-columns: repeat(
+		auto-fit,
+		minmax(
+			min(100%, var(--monster-surface-grid-min-inline-size, 20rem)),
+			1fr
+		)
+	);
+	gap: var(--monster-surface-grid-gap, var(--monster-space-5));
+	align-items: stretch;
+}
+
+.monster-surface-actions {
+	display: flex;
+	flex-wrap: wrap;
+	align-items: center;
+	gap: var(--monster-surface-actions-gap, var(--monster-space-3));
+	margin-block-start: auto;
+}

package/source/components/stylesheet/surface.mjs

@@ -0,0 +1,38 @@
+/**
+ * Copyright © Volker Schukai and all contributing authors, 2026. 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.
+ */
+
+import { addAttributeToken } from "../../dom/attributes.mjs";
+import { ATTRIBUTE_ERRORMESSAGE } from "../../dom/constants.mjs";
+
+export { SurfaceStyleSheet };
+
+/**
+ * @private
+ * @type {CSSStyleSheet}
+ */
+const SurfaceStyleSheet = new CSSStyleSheet();
+
+try {
+	SurfaceStyleSheet.insertRule(
+		`
+@layer surface {
+:where(.monster-surface){box-sizing:border-box;min-inline-size:0;display:grid;gap:var(--monster-surface-gap,var(--monster-space-3));padding:var(--monster-surface-padding,var(--monster-space-5));border-width:var(--monster-border-width);border-style:var(--monster-border-style);border-color:var(--monster-color-border-1);border-radius:var(--monster-border-radius);box-shadow:var(--monster-box-shadow-1)}.monster-surface-grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(min(100%,var(--monster-surface-grid-min-inline-size,20rem)),1fr));gap:var(--monster-surface-grid-gap,var(--monster-space-5));align-items:stretch}.monster-surface-actions{display:flex;flex-wrap:wrap;align-items:center;gap:var(--monster-surface-actions-gap,var(--monster-space-3));margin-block-start:auto}
+}`,
+		0,
+	);
+} catch (e) {
+	addAttributeToken(
+		document.getRootNode().querySelector("html"),
+		ATTRIBUTE_ERRORMESSAGE,
+		e + "",
+	);
+}

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.1.0");
 
 	return monsterVersion;
 }

package/test/cases/components/style/surface.mjs

@@ -0,0 +1,50 @@
+import { readFileSync } from "node:fs";
+import { expect } from "chai";
+
+const source = readFileSync(
+	new URL("../../../../source/components/style/surface.pcss", import.meta.url),
+	"utf8",
+);
+const generatedStyleSheet = readFileSync(
+	new URL(
+		"../../../../source/components/stylesheet/surface.mjs",
+		import.meta.url,
+	),
+	"utf8",
+);
+
+describe("Content surfaces", () => {
+	it("provides theme-composable static content geometry", () => {
+		expect(source).to.include(":where(.monster-surface)");
+		expect(source).to.include(
+			"gap: var(--monster-surface-gap, var(--monster-space-3));",
+		);
+		expect(source).to.include(
+			"padding: var(--monster-surface-padding, var(--monster-space-5));",
+		);
+		expect(source).to.include("border-width: var(--monster-border-width);");
+		expect(source).to.include("border-style: var(--monster-border-style);");
+		expect(source).to.include("border-color: var(--monster-color-border-1);");
+		expect(source).to.include("border-radius: var(--monster-border-radius);");
+		expect(source).not.to.match(/^\s*(?:background-color|color):/mu);
+	});
+
+	it("provides reusable responsive grids and action rows", () => {
+		expect(source).to.include(".monster-surface-grid");
+		expect(source).to.include("grid-template-columns: repeat(");
+		expect(source).to.include("auto-fit,");
+		expect(source).to.include(".monster-surface-actions");
+		expect(source).to.include("margin-block-start: auto;");
+	});
+
+	it("keeps the generated stylesheet synchronized", () => {
+		expect(generatedStyleSheet).to.include(":where(.monster-surface)");
+		expect(generatedStyleSheet).to.include(
+			"gap:var(--monster-surface-gap,var(--monster-space-3))",
+		);
+		expect(generatedStyleSheet).to.include(
+			"grid-template-columns:repeat(auto-fit,minmax(min(100%,var(--monster-surface-grid-min-inline-size,20rem)),1fr))",
+		);
+		expect(generatedStyleSheet).to.include(".monster-surface-actions");
+	});
+});

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 () {