@schukai/monster 5.0.1 → 5.1.1

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 
 
+## [5.1.1] - 2026-10-11
+
+### Bug Fixes
+
+- **control-bar:** use container space for intrinsically sized hosts ([#603](https://gitlab.schukai.com/oss/libraries/javascript/monster/issues/603))
+
+
+
+## [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

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","./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"}
+{"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.1"}

package/source/components/form/control-bar.mjs

@@ -262,6 +262,14 @@ const VISUAL_BORDER_CONTROL_SELECTOR = [
  * - `monster-control-bar-layout-changed` is emitted when responsive layout state changes.
  * - The event detail contains `{alignment, configuredAlignment, stacked, stackedAlignment, stackedBreakpoint, stackedBreakpointContainer}`.
  *
+ * Available width:
+ * - The bar lays out its controls in the content width of its parent element.
+ * - A host that is narrower than its parent limits that width only when it cannot grow,
+ *   for example because of an explicit `width`, `inline-size` or `max-width`.
+ * - A host whose width follows its content (grid item with `justify-self`, `auto` grid column,
+ *   flex item without `flex-grow`) does not limit the width; its controls stay in the main row
+ *   as long as the parent offers enough room.
+ *
  * @fires monster-control-bar-layout-changed
  */
 class ControlBar extends CustomElement {
@@ -1807,15 +1815,6 @@ function calculateControlBarDimensions() {
 		);
 	}
 
-	const hostContentWidth = getElementContentWidth(this);
-	if (hostContentWidth > 0) {
-		const measuredSpace = this[dimensionsSymbol].getVia("data.space", 0);
-		this[dimensionsSymbol].setVia(
-			"data.space",
-			Math.min(measuredSpace, hostContentWidth),
-		);
-	}
-
 	this[dimensionsSymbol].setVia("data.visible", !(containerWidth === 0));
 	this[dimensionsSymbol].setVia("data.containerWidth", containerWidth);
 	this[dimensionsSymbol].setVia(
@@ -1885,10 +1884,137 @@ function calculateControlBarDimensions() {
 		this[dimensionsSymbol].setVia("data.switchWidth", switchWidth);
 	}
 
+	limitSpaceToHostCapacity.call(this, itemReferences);
+
 	this[dimensionsSymbol].setVia("data.calculated", true);
 	this[dimensionsSymbol].setVia("data.itemReferences", itemReferences);
 }
 
+/**
+ * Limits the available space to the host when the host is narrower than its
+ * container for a reason that does not depend on its content, such as an
+ * explicit `width` or `max-width`.
+ *
+ * A host whose width follows its content (grid item with `justify-self`,
+ * `auto` grid column, flex item without `flex-grow`) must not limit the space:
+ * its current width is the result of the previous layout. Once a control has
+ * been moved into the popper, such a host shrinks to the overflow switch and
+ * would never offer room for the control again. The host is therefore probed
+ * with the width the controls need; only a host that cannot grow limits the
+ * space.
+ *
+ * @private
+ * @param {string[]} itemReferences
+ * @return {void}
+ */
+function limitSpaceToHostCapacity(itemReferences) {
+	const hostContentWidth = getElementContentWidth(this);
+	if (!(hostContentWidth > 0)) {
+		return;
+	}
+
+	let measuredSpace = 0;
+	try {
+		measuredSpace = this[dimensionsSymbol].getVia("data.space", 0);
+	} catch {}
+
+	if (hostContentWidth >= measuredSpace) {
+		return;
+	}
+
+	const requiredWidth = getRequiredItemWidth.call(this, itemReferences);
+	let hostCapacity = hostContentWidth;
+	if (requiredWidth > hostCapacity) {
+		hostCapacity = measureHostCapacity.call(this, requiredWidth);
+	}
+
+	if (requiredWidth > hostCapacity) {
+		this[dimensionsSymbol].setVia(
+			"data.space",
+			Math.min(measuredSpace, hostCapacity),
+		);
+	}
+}
+
+/**
+ * Sums the stored widths of all controls that are not hidden by themselves,
+ * regardless of whether they are currently in the main row or in the popper.
+ *
+ * @private
+ * @param {string[]} itemReferences
+ * @return {number}
+ */
+function getRequiredItemWidth(itemReferences) {
+	const widthByReference = new Map();
+	for (const ref of itemReferences) {
+		try {
+			widthByReference.set(
+				ref,
+				this[dimensionsSymbol].getVia(`data.item.${ref}`),
+			);
+		} catch {
+			// Items that have never been visible have no stored width.
+		}
+	}
+
+	let requiredWidth = 0;
+	const counted = new Set();
+	for (const item of this.children) {
+		if (!(item instanceof HTMLElement) || isElementSelfHidden(item)) {
+			continue;
+		}
+		const ref = item.getAttribute("data-monster-reference");
+		if (ref === null || counted.has(ref) || !widthByReference.has(ref)) {
+			continue;
+		}
+		counted.add(ref);
+		requiredWidth += widthByReference.get(ref) || 0;
+	}
+
+	return requiredWidth;
+}
+
+/**
+ * Measures how wide the host content box becomes when the shadow control
+ * container requests at least the given width. The probe is applied and
+ * removed within the same synchronous layout pass, so observers never see it.
+ *
+ * A host with an explicit `width` or `max-width` keeps its size, a host whose
+ * width follows its content grows with the request.
+ *
+ * @private
+ * @param {number} requiredWidth
+ * @return {number}
+ */
+function measureHostCapacity(requiredWidth) {
+	const control = this[controlElementSymbol];
+	if (!(control instanceof HTMLElement)) {
+		return getElementContentWidth(this);
+	}
+
+	const previousValue = control.style.getPropertyValue("min-inline-size");
+	const previousPriority = control.style.getPropertyPriority("min-inline-size");
+	control.style.setProperty(
+		"min-inline-size",
+		`${Math.ceil(requiredWidth)}px`,
+		"important",
+	);
+
+	try {
+		return getElementContentWidth(this);
+	} finally {
+		if (previousValue === "") {
+			control.style.removeProperty("min-inline-size");
+		} else {
+			control.style.setProperty(
+				"min-inline-size",
+				previousValue,
+				previousPriority,
+			);
+		}
+	}
+}
+
 /**
  * @private
  * @param {HTMLElement} element

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.1");
+	monsterVersion = new Version("5.1.1");
 
 	return monsterVersion;
 }

package/test/cases/components/form/button-bar.mjs

@@ -280,6 +280,106 @@ describe("ButtonBar", function () {
     }
   });
 
+  it("should not limit the space to a host whose width follows its content (#603)", async function () {
+    const originalRequestAnimationFrame = window.requestAnimationFrame;
+    const originalGlobalRequestAnimationFrame = globalThis.requestAnimationFrame;
+    const scheduledCallbacks = [];
+    const flushFrames = async () => {
+      while (scheduledCallbacks.length > 0) {
+        scheduledCallbacks.shift()();
+        await new Promise((resolve) => setTimeout(resolve, 0));
+      }
+      await new Promise((resolve) => setTimeout(resolve, 0));
+    };
+
+    try {
+      window.requestAnimationFrame = (callback) => {
+        scheduledCallbacks.push(callback);
+        return scheduledCallbacks.length;
+      };
+      globalThis.requestAnimationFrame = window.requestAnimationFrame;
+
+      const mocks = document.getElementById("mocks");
+      mocks.innerHTML = `
+        <div id="intrinsic-wrapper">
+          <monster-button-bar id="intrinsic-button-bar">
+            <button id="intrinsic-a" type="button">One</button>
+            <button id="intrinsic-b" type="button">Two</button>
+          </monster-button-bar>
+        </div>
+      `;
+      const wrapper = document.getElementById("intrinsic-wrapper");
+      const bar = document.getElementById("intrinsic-button-bar");
+      const buttons = [
+        document.getElementById("intrinsic-a"),
+        document.getElementById("intrinsic-b"),
+      ];
+      const control = bar.shadowRoot.querySelector(
+        '[data-monster-role="control"]',
+      );
+      const switchButton = bar.shadowRoot.querySelector(
+        '[data-monster-role="switch"]',
+      );
+
+      wrapper.style.boxSizing = "border-box";
+      Object.defineProperty(wrapper, "clientWidth", {
+        configurable: true,
+        value: 600,
+      });
+      // The host collapsed to the switch after an earlier overflow, but its
+      // width follows its content: it takes any width the bar probes for.
+      const probes = [];
+      Object.defineProperty(bar, "clientWidth", {
+        configurable: true,
+        get: () => {
+          const requested = parseFloat(control.style.minInlineSize) || 0;
+          if (requested > 0) {
+            probes.push(requested);
+          }
+          return Math.max(44, requested);
+        },
+      });
+      Object.defineProperty(switchButton, "offsetWidth", {
+        configurable: true,
+        value: 40,
+      });
+
+      for (const button of buttons) {
+        Object.defineProperty(button, "offsetWidth", {
+          configurable: true,
+          value: 114,
+        });
+        Object.defineProperty(button, "offsetHeight", {
+          configurable: true,
+          value: 30,
+        });
+        button.getBoundingClientRect = () => ({
+          width: 114.2,
+          height: 30,
+          top: 0,
+          right: 114.2,
+          bottom: 30,
+          left: 0,
+          x: 0,
+          y: 0,
+          toJSON: () => {},
+        });
+      }
+
+      await flushFrames();
+
+      expect(buttons.map((button) => button.getAttribute("slot"))).to.deep.equal(
+        [null, null],
+      );
+      expect(switchButton.hasAttribute("hidden")).to.be.true;
+      expect(probes).to.include(229);
+      expect(control.style.minInlineSize).to.equal("");
+    } finally {
+      window.requestAnimationFrame = originalRequestAnimationFrame;
+      globalThis.requestAnimationFrame = originalGlobalRequestAnimationFrame;
+    }
+  });
+
   it("should use the host content box when reserving overflow switch space", async function () {
     const originalRequestAnimationFrame = window.requestAnimationFrame;
     const originalGlobalRequestAnimationFrame = globalThis.requestAnimationFrame;

package/test/cases/components/form/control-bar.mjs

@@ -3017,4 +3017,227 @@ describe("ControlBar", function () {
       globalThis.requestAnimationFrame = originalGlobalRequestAnimationFrame;
     }
   });
+
+  describe("host width (#603)", function () {
+    const BUTTON_WIDTH = 114.2;
+    const SWITCH_WIDTH = 40;
+    let restore;
+
+    afterEach(function () {
+      if (typeof restore === "function") {
+        restore();
+        restore = null;
+      }
+      document.getElementById("mocks").replaceChildren();
+    });
+
+    /**
+     * Mounts a bar with two controls inside a 600px wrapper. The host's
+     * clientWidth is simulated by `hostWidth`, which receives the min width the
+     * bar requests on its shadow control container during the probe (or 0).
+     */
+    async function mountBar({ hostWidth }) {
+      const OriginalResizeObserver = window.ResizeObserver;
+      const originalGlobalResizeObserver = globalThis.ResizeObserver;
+      const originalRequestAnimationFrame = window.requestAnimationFrame;
+      const originalGlobalRequestAnimationFrame =
+        globalThis.requestAnimationFrame;
+
+      class TrackingResizeObserver extends ResizeObserverMock {
+        static instances = [];
+
+        constructor(callback) {
+          super(callback);
+          TrackingResizeObserver.instances.push(this);
+        }
+      }
+
+      const scheduledCallbacks = [];
+      const flushFrames = async () => {
+        while (scheduledCallbacks.length > 0) {
+          scheduledCallbacks.shift()();
+          await new Promise((resolve) => setTimeout(resolve, 0));
+        }
+        await new Promise((resolve) => setTimeout(resolve, 0));
+      };
+
+      restore = () => {
+        window.ResizeObserver = OriginalResizeObserver;
+        globalThis.ResizeObserver = originalGlobalResizeObserver;
+        window.requestAnimationFrame = originalRequestAnimationFrame;
+        globalThis.requestAnimationFrame = originalGlobalRequestAnimationFrame;
+      };
+
+      window.ResizeObserver = TrackingResizeObserver;
+      globalThis.ResizeObserver = TrackingResizeObserver;
+      window.requestAnimationFrame = (callback) => {
+        scheduledCallbacks.push(callback);
+        return scheduledCallbacks.length;
+      };
+      globalThis.requestAnimationFrame = window.requestAnimationFrame;
+
+      const mocks = document.getElementById("mocks");
+      mocks.innerHTML = `
+        <div id="host-width-wrapper">
+          <monster-control-bar id="host-width-bar">
+            <button id="host-width-one" type="button">One</button>
+            <button id="host-width-two" type="button">Two</button>
+          </monster-control-bar>
+        </div>
+      `;
+
+      const wrapper = document.getElementById("host-width-wrapper");
+      const bar = document.getElementById("host-width-bar");
+      const controls = [
+        document.getElementById("host-width-one"),
+        document.getElementById("host-width-two"),
+      ];
+      const control = bar.shadowRoot.querySelector(
+        '[data-monster-role="control"]',
+      );
+      const switchButton = bar.shadowRoot.querySelector(
+        '[data-monster-role="switch"]',
+      );
+
+      let wrapperWidth = 600;
+      wrapper.style.boxSizing = "border-box";
+      Object.defineProperty(wrapper, "clientWidth", {
+        configurable: true,
+        get: () => wrapperWidth,
+      });
+
+      const probes = [];
+      Object.defineProperty(bar, "clientWidth", {
+        configurable: true,
+        get: () => {
+          const requested = parseFloat(control.style.minInlineSize) || 0;
+          if (requested > 0) {
+            probes.push(requested);
+          }
+          return hostWidth(requested);
+        },
+      });
+
+      for (const button of controls) {
+        Object.defineProperty(button, "offsetWidth", {
+          configurable: true,
+          value: Math.floor(BUTTON_WIDTH),
+        });
+        Object.defineProperty(button, "offsetHeight", {
+          configurable: true,
+          value: 30,
+        });
+        button.getBoundingClientRect = () => ({
+          width: BUTTON_WIDTH,
+          height: 30,
+          top: 0,
+          right: BUTTON_WIDTH,
+          bottom: 30,
+          left: 0,
+          x: 0,
+          y: 0,
+          toJSON: () => {},
+        });
+      }
+      Object.defineProperty(switchButton, "offsetWidth", {
+        configurable: true,
+        value: SWITCH_WIDTH,
+      });
+
+      await flushFrames();
+
+      const resizeObserver = TrackingResizeObserver.instances.find((observer) =>
+        observer.elements.includes(wrapper),
+      );
+
+      return {
+        bar,
+        controls,
+        control,
+        switchButton,
+        probes,
+        flushFrames,
+        resizeWrapper: async (width) => {
+          wrapperWidth = width;
+          resizeObserver.triggerResize([{ target: wrapper }]);
+          await flushFrames();
+        },
+      };
+    }
+
+    const slots = (controls) =>
+      controls.map((control) => control.getAttribute("slot"));
+
+    it("should not limit the space to a host whose width follows its content", async function () {
+      // The host currently shows only the overflow switch, as after a
+      // previous overflow, but grows to whatever its content requests.
+      const { controls, control, switchButton, probes } = await mountBar({
+        hostWidth: (requested) => Math.max(44, requested),
+      });
+
+      expect(slots(controls)).to.deep.equal([null, null]);
+      expect(switchButton.hasAttribute("hidden")).to.be.true;
+      expect(probes).to.include(Math.ceil(BUTTON_WIDTH * 2));
+      expect(control.style.minInlineSize).to.equal("");
+    });
+
+    it("should keep limiting the space to a host that cannot grow", async function () {
+      const { controls, control, switchButton, probes } = await mountBar({
+        hostWidth: () => 80,
+      });
+
+      expect(slots(controls)).to.deep.equal(["popper", "popper"]);
+      expect(switchButton.hasAttribute("hidden")).to.be.false;
+      expect(probes).to.include(Math.ceil(BUTTON_WIDTH * 2));
+      expect(control.style.minInlineSize).to.equal("");
+    });
+
+    it("should use the width a constrained host can still offer", async function () {
+      // max-width style limit: the host grows, but only up to 200px.
+      const { controls, switchButton } = await mountBar({
+        hostWidth: (requested) => Math.min(200, Math.max(44, requested)),
+      });
+
+      expect(slots(controls)).to.deep.equal([null, "popper"]);
+      expect(switchButton.hasAttribute("hidden")).to.be.false;
+    });
+
+    it("should not probe a host that already fills its container", async function () {
+      const { controls, probes } = await mountBar({
+        hostWidth: () => 600,
+      });
+
+      expect(slots(controls)).to.deep.equal([null, null]);
+      expect(probes).to.be.empty;
+    });
+
+    it("should not probe a narrower host when the controls already fit", async function () {
+      const { controls, probes, switchButton } = await mountBar({
+        hostWidth: () => 300,
+      });
+
+      expect(slots(controls)).to.deep.equal([null, null]);
+      expect(switchButton.hasAttribute("hidden")).to.be.true;
+      expect(probes).to.be.empty;
+    });
+
+    it("should restore controls into an intrinsic host after the container grows again", async function () {
+      let visibleWidth = BUTTON_WIDTH * 2;
+      const { controls, switchButton, resizeWrapper } = await mountBar({
+        // The intrinsic host is as wide as its visible content, but takes any
+        // requested width.
+        hostWidth: (requested) => Math.max(Math.floor(visibleWidth), requested),
+      });
+      expect(slots(controls)).to.deep.equal([null, null]);
+
+      visibleWidth = SWITCH_WIDTH;
+      await resizeWrapper(100);
+      expect(slots(controls)).to.deep.equal(["popper", "popper"]);
+      expect(switchButton.hasAttribute("hidden")).to.be.false;
+
+      await resizeWrapper(600);
+      expect(slots(controls)).to.deep.equal([null, null]);
+      expect(switchButton.hasAttribute("hidden")).to.be.true;
+    });
+  });
 });

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");
+	});
+});