@schukai/monster 4.147.1 → 4.148.0

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.","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.147.1"}
+{"author":"Volker Schukai","dependencies":{"@floating-ui/dom":"^1.7.6"},"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.148.0"}

package/source/components/form/choice-cards.mjs

@@ -39,7 +39,7 @@ const controlElementSymbol = Symbol("controlElement");
 const itemsElementSymbol = Symbol("itemsElement");
 
 /**
- * A card-based single choice control.
+ * A card-based choice control.
  *
  * @fragments /fragments/components/form/choice-cards
  *
@@ -47,11 +47,13 @@ const itemsElementSymbol = Symbol("itemsElement");
  *
  * @since 4.137.0
  * @copyright Volker Schukai
- * @summary A visual radio-card picker for choosing one option from a compact set.
+ * @summary A visual card picker for choosing one or multiple options from a compact set.
  *
  * Event details:
- * - `monster-selected`, `monster-change` and `monster-changed` use
- *   `{value: string|null, item: Object|null}`.
+ * - In single-select mode, `monster-selected`, `monster-change` and
+ *   `monster-changed` use `{value: string|null, item: Object|null}`.
+ * - In multi-select mode, event details use
+ *   `{value: Array<string>, item: Object|null, selected: boolean}`.
  * - The native `change` event is emitted before the custom Monster events.
  *
  * @fires monster-selected
@@ -70,7 +72,8 @@ class ChoiceCards extends CustomControl {
 	 * @property {string} items[].iconSlot Slot name for custom icon content.
 	 * @property {string} items[].contentSlot Slot name for custom card content. The shorter `slot` field is accepted as alias.
 	 * @property {boolean} items[].disabled Disables a single choice while keeping it visible.
-	 * @property {string|null} value Current selected value.
+	 * @property {string|null|Array<string>} value Current selected value. Multi-select mode uses an array.
+	 * @property {boolean} multiple Enables independent on/off selection for multiple cards.
 	 * @property {boolean} disabled Disabled state.
 	 * @property {Object} labels Accessible labels.
 	 * @property {string} labels.group Radio group label.
@@ -81,6 +84,7 @@ class ChoiceCards extends CustomControl {
 		return Object.assign({}, super.defaults, {
 			items: [],
 			value: null,
+			multiple: false,
 			disabled: false,
 			eventProcessing: false,
 			labels: {
@@ -136,21 +140,26 @@ class ChoiceCards extends CustomControl {
 	}
 
 	/**
-	 * @return {string}
+	 * @return {string|null|Array<string>}
 	 */
 	get value() {
-		return this.getOption("value");
+		return normalizeControlValue(
+			this.getOption("value"),
+			isMultiple.call(this),
+		);
 	}
 
 	/**
-	 * @param {string|null|undefined} value
+	 * @param {string|Array<string>|null|undefined} value
 	 */
 	set value(value) {
-		const normalized = normalizeValue(value);
-		if (this.getOption("value") !== normalized) {
+		const multiple = isMultiple.call(this);
+		const normalized = normalizeControlValue(value, multiple);
+		const current = normalizeControlValue(this.getOption("value"), multiple);
+		if (!valuesEqual(current, normalized)) {
 			this.setOption("value", normalized);
 		}
-		syncValueAttribute.call(this, normalized);
+		syncValueAttribute.call(this, normalized, multiple);
 		render.call(this);
 		syncFormValue.call(this);
 	}
@@ -189,6 +198,10 @@ class ChoiceCards extends CustomControl {
 			return this;
 		}
 
+		if (isMultiple.call(this)) {
+			return toggleMultipleSelection.call(this, normalized, item || null);
+		}
+
 		if (this.value === normalized) {
 			return this;
 		}
@@ -227,7 +240,13 @@ function initControlReferences() {
  */
 function initItems() {
 	if (this.hasAttribute("value")) {
-		this.setOption("value", normalizeValue(this.getAttribute("value")));
+		this.setOption(
+			"value",
+			normalizeControlValue(
+				this.getAttribute("value"),
+				isMultiple.call(this),
+			),
+		);
 	}
 
 	const normalized = normalizeItems(this.getOption("items", []));
@@ -274,29 +293,32 @@ function initEventHandler() {
 			return;
 		}
 
+		const multiple = isMultiple.call(this);
+
 		if (event.key === "Home") {
 			event.preventDefault();
-			focusAndSelect.call(this, buttons[0]);
+			focusButton.call(this, buttons[0], !multiple);
 			return;
 		}
 
 		if (event.key === "End") {
 			event.preventDefault();
-			focusAndSelect.call(this, buttons[buttons.length - 1]);
+			focusButton.call(this, buttons[buttons.length - 1], !multiple);
 			return;
 		}
 
 		if (["ArrowRight", "ArrowDown"].includes(event.key)) {
 			event.preventDefault();
-			focusAndSelect.call(this, buttons[(index + 1) % buttons.length]);
+			focusButton.call(this, buttons[(index + 1) % buttons.length], !multiple);
 			return;
 		}
 
 		if (["ArrowLeft", "ArrowUp"].includes(event.key)) {
 			event.preventDefault();
-			focusAndSelect.call(
+			focusButton.call(
 				this,
 				buttons[(index - 1 + buttons.length) % buttons.length],
+				!multiple,
 			);
 		}
 	});
@@ -305,11 +327,14 @@ function initEventHandler() {
 /**
  * @private
  * @param {HTMLButtonElement} button
+ * @param {boolean} select
  * @return {void}
  */
-function focusAndSelect(button) {
+function focusButton(button, select) {
 	button.focus();
-	this.select(button.getAttribute("data-choice-value"));
+	if (select === true) {
+		this.select(button.getAttribute("data-choice-value"));
+	}
 }
 
 /**
@@ -349,10 +374,14 @@ function render() {
 	}
 
 	const items = normalizeItems(this.getOption("items", []));
-	const value = normalizeValue(this.getOption("value"));
+	const multiple = isMultiple.call(this);
+	const value = normalizeControlValue(this.getOption("value"), multiple);
+	const selectedValues = multiple ? value : [];
 	const disabled =
 		this.getOption("disabled") === true || this.hasAttribute("disabled");
-	const hasSelectedItem = items.some((item) => item.value === value);
+	const hasSelectedItem = items.some((item) =>
+		multiple ? selectedValues.includes(item.value) : item.value === value,
+	);
 	const firstEnabledIndex = items.findIndex((item) => item.disabled !== true);
 
 	this[itemsElementSymbol].replaceChildren();
@@ -360,17 +389,24 @@ function render() {
 		"aria-label",
 		this.getOption("labels.group", "Choices"),
 	);
+	this[controlElementSymbol]?.setAttribute(
+		"role",
+		multiple ? "group" : "radiogroup",
+	);
 
 	for (const [index, item] of items.entries()) {
-		const selected = value !== null && item.value === value;
-		const tabbable =
-			selected || (hasSelectedItem === false && index === firstEnabledIndex);
+		const selected = multiple
+			? selectedValues.includes(item.value)
+			: value !== null && item.value === value;
+		const tabbable = multiple
+			? item.disabled !== true
+			: selected || (hasSelectedItem === false && index === firstEnabledIndex);
 		const button = document.createElement("button");
 		button.type = "button";
 		button.setAttribute("data-monster-role", "choice");
 		button.setAttribute("data-choice-value", item.value);
 		button.setAttribute("part", "choice");
-		button.setAttribute("role", "radio");
+		button.setAttribute("role", multiple ? "checkbox" : "radio");
 		button.setAttribute("aria-label", item.label);
 		button.setAttribute("aria-checked", selected ? "true" : "false");
 		button.tabIndex = tabbable ? 0 : -1;
@@ -430,6 +466,14 @@ function findItem(value) {
 	);
 }
 
+/**
+ * @private
+ * @return {boolean}
+ */
+function isMultiple() {
+	return this.getOption("multiple") === true;
+}
+
 /**
  * @private
  * @param {*} value
@@ -442,6 +486,61 @@ function normalizeValue(value) {
 	return String(value);
 }
 
+/**
+ * @private
+ * @param {*} value
+ * @param {boolean} multiple
+ * @return {string|null|Array<string>}
+ */
+function normalizeControlValue(value, multiple) {
+	if (multiple === true) {
+		return normalizeValues(value);
+	}
+	return normalizeValue(value);
+}
+
+/**
+ * @private
+ * @param {*} value
+ * @return {Array<string>}
+ */
+function normalizeValues(value) {
+	if (value === undefined || value === null || value === "") {
+		return [];
+	}
+
+	const raw = isArray(value)
+		? value
+		: isString(value)
+			? value.split("::")
+			: [value];
+	const normalized = raw
+		.map((entry) => normalizeValue(entry))
+		.filter((entry) => entry !== null);
+
+	return Array.from(new Set(normalized));
+}
+
+/**
+ * @private
+ * @param {string|null|Array<string>} current
+ * @param {string|null|Array<string>} next
+ * @return {boolean}
+ */
+function valuesEqual(current, next) {
+	if (isArray(current) || isArray(next)) {
+		if (!isArray(current) || !isArray(next)) {
+			return false;
+		}
+		if (current.length !== next.length) {
+			return false;
+		}
+		return current.every((value, index) => value === next[index]);
+	}
+
+	return current === next;
+}
+
 /**
  * @private
  * @param {*} items
@@ -493,28 +592,94 @@ function normalizeItems(items) {
  */
 function syncFormValue() {
 	if (typeof this.setFormValue === "function") {
+		if (isMultiple.call(this)) {
+			const values = normalizeValues(this.value);
+			const serialized = serializeValues(values);
+			this.setFormValue(serialized, serialized);
+			return;
+		}
+
 		this.setFormValue(this.value ?? "");
 	}
 }
 
 /**
  * @private
- * @param {string|null} value
+ * @param {string|null|Array<string>} value
+ * @param {boolean} multiple
  * @return {void}
  */
-function syncValueAttribute(value) {
-	if (value === null) {
+function syncValueAttribute(value, multiple) {
+	const attributeValue = multiple ? serializeValues(value) : value;
+	if (attributeValue === null || attributeValue === "") {
 		if (this.hasAttribute("value")) {
 			this.removeAttribute("value");
 		}
 		return;
 	}
 
-	if (this.getAttribute("value") !== value) {
-		this.setAttribute("value", value);
+	if (this.getAttribute("value") !== attributeValue) {
+		this.setAttribute("value", attributeValue);
 	}
 }
 
+/**
+ * @private
+ * @param {Array<string>|string|null} values
+ * @return {string}
+ */
+function serializeValues(values) {
+	return normalizeValues(values).join("::");
+}
+
+/**
+ * @private
+ * @param {string|null} value
+ * @param {Object|null} item
+ * @return {ChoiceCards}
+ */
+function toggleMultipleSelection(value, item) {
+	const current = normalizeValues(this.value);
+	if (value === null) {
+		if (current.length === 0) {
+			return this;
+		}
+		this.value = [];
+		fireSelectionEvents.call(this, {
+			value: this.value,
+			item: null,
+			selected: false,
+		});
+		return this;
+	}
+
+	const selected = current.includes(value);
+	const next = selected
+		? current.filter((entry) => entry !== value)
+		: current.concat(value);
+
+	this.value = next;
+	fireSelectionEvents.call(this, {
+		value: this.value,
+		item,
+		selected: !selected,
+	});
+
+	return this;
+}
+
+/**
+ * @private
+ * @param {Object} detail
+ * @return {void}
+ */
+function fireSelectionEvents(detail) {
+	fireEvent(this, "change");
+	fireCustomEvent(this, "monster-selected", detail);
+	fireCustomEvent(this, "monster-change", detail);
+	fireCustomEvent(this, "monster-changed", detail);
+}
+
 /**
  * @private
  * @return {string}

package/test/cases/components/form/choice-cards.mjs

@@ -132,6 +132,86 @@ describe("ChoiceCards", function () {
     cards.shadowRoot.querySelector('[data-choice-value="api"]').click();
   });
 
+  it("toggles multiple cards when the multiple option is enabled", function () {
+    const cards = document.createElement("monster-choice-cards");
+    cards.setOption("multiple", true);
+    cards.setItems([
+      { value: "assets", label: "Project assets" },
+      { value: "api", label: "API collection" },
+      { value: "manual", label: "Manual" },
+    ]);
+
+    const changes = [];
+    cards.addEventListener("monster-change", (event) => {
+      changes.push(event.detail);
+    });
+
+    document.getElementById("test").appendChild(cards);
+
+    expect(
+      cards.shadowRoot
+        .querySelector('[data-monster-role="control"]')
+        .getAttribute("role"),
+    ).is.equal("group");
+    expect(
+      cards.shadowRoot
+        .querySelector('[data-choice-value="assets"]')
+        .getAttribute("role"),
+    ).is.equal("checkbox");
+
+    cards.shadowRoot.querySelector('[data-choice-value="assets"]').click();
+    cards.shadowRoot.querySelector('[data-choice-value="api"]').click();
+    cards.shadowRoot.querySelector('[data-choice-value="assets"]').click();
+
+    expect(cards.value).deep.equal(["api"]);
+    expect(
+      cards.shadowRoot
+        .querySelector('[data-choice-value="assets"]')
+        .getAttribute("aria-checked"),
+    ).is.equal("false");
+    expect(
+      cards.shadowRoot
+        .querySelector('[data-choice-value="api"]')
+        .getAttribute("aria-checked"),
+    ).is.equal("true");
+    expect(changes.length).is.equal(3);
+    expect(changes[0].value).deep.equal(["assets"]);
+    expect(changes[0].selected).is.equal(true);
+    expect(changes[2].value).deep.equal(["api"]);
+    expect(changes[2].selected).is.equal(false);
+  });
+
+  it("reads multiple values from the value attribute", function () {
+    document.getElementById("test").innerHTML = `
+      <monster-choice-cards
+        id="multi-attribute"
+        value="assets::api"
+        data-monster-option-multiple="true"
+        data-monster-options='{
+          "items": [
+            { "value": "assets", "label": "Assets" },
+            { "value": "api", "label": "API" },
+            { "value": "manual", "label": "Manual" }
+          ]
+        }'
+      ></monster-choice-cards>
+    `;
+
+    const cards = document.getElementById("multi-attribute");
+
+    expect(cards.value).deep.equal(["assets", "api"]);
+    expect(
+      cards.shadowRoot
+        .querySelector('[data-choice-value="assets"]')
+        .getAttribute("aria-checked"),
+    ).is.equal("true");
+    expect(
+      cards.shadowRoot
+        .querySelector('[data-choice-value="manual"]')
+        .getAttribute("aria-checked"),
+    ).is.equal("false");
+  });
+
   it("reads from and writes back to a form datasource", async function () {
     this.timeout(6000);
 
@@ -177,6 +257,80 @@ describe("ChoiceCards", function () {
     await waitForCondition(() => datasource.data?.[0]?.source === "api");
   });
 
+  it("writes multiple values back to a form datasource", async function () {
+    this.timeout(6000);
+
+    document.getElementById("test").innerHTML = `
+      <monster-datasource-dom id="multi-choice-ds">
+        <script type="application/json">
+          [
+            {
+              "sources": []
+            }
+          ]
+        </script>
+      </monster-datasource-dom>
+      <monster-form
+        id="multi-choice-form"
+        data-monster-option-datasource-selector="#multi-choice-ds"
+        data-monster-option-mapping-data=""
+        data-monster-option-mapping-index="0"
+      >
+        <monster-choice-cards
+          id="multi-choice-source"
+          data-monster-attributes="value path:data.sources"
+          data-monster-bind="path:data.sources"
+          data-monster-option-multiple="true"
+          data-monster-options='{
+            "items": [
+              { "value": "assets", "label": "Assets" },
+              { "value": "api", "label": "API" },
+              { "value": "manual", "label": "Manual" }
+            ]
+          }'
+        ></monster-choice-cards>
+      </monster-form>
+    `;
+
+    const datasource = document.getElementById("multi-choice-ds");
+    const cards = document.getElementById("multi-choice-source");
+
+    await waitForCondition(() => Array.isArray(datasource.data?.[0]?.sources));
+    await new Promise((resolve) => setTimeout(resolve, 500));
+
+    cards.select("assets");
+    await waitForCondition(
+      () => JSON.stringify(datasource.data?.[0]?.sources) === '["assets"]',
+    );
+
+    cards.select("api");
+
+    await waitForCondition(
+      () => JSON.stringify(datasource.data?.[0]?.sources) === '["assets","api"]',
+    );
+  });
+
+  it("submits multiple values through form data", function () {
+    const form = document.createElement("form");
+    const cards = document.createElement("monster-choice-cards");
+    cards.setAttribute("name", "sources");
+    cards.setOption("multiple", true);
+    cards.setItems([
+      { value: "assets", label: "Project assets" },
+      { value: "api", label: "API collection" },
+      { value: "manual", label: "Manual" },
+    ]);
+
+    form.appendChild(cards);
+    document.getElementById("test").appendChild(form);
+
+    cards.select("assets");
+    cards.select("api");
+
+    const formData = new window.FormData(form);
+    expect(formData.getAll("sources")).deep.equal(["assets::api"]);
+  });
+
   it("does not select disabled items", function () {
     const cards = document.createElement("monster-choice-cards");
     cards.setItems([
@@ -189,4 +343,24 @@ describe("ChoiceCards", function () {
 
     expect(cards.value).is.equal(null);
   });
+
+  it("does not toggle disabled items in multiple mode", function () {
+    const cards = document.createElement("monster-choice-cards");
+    cards.setOption("multiple", true);
+    cards.setItems([
+      { value: "assets", label: "Project assets" },
+      { value: "api", label: "API collection", disabled: true },
+    ]);
+
+    document.getElementById("test").appendChild(cards);
+    cards.select("assets");
+    cards.select("api");
+
+    expect(cards.value).deep.equal(["assets"]);
+    expect(
+      cards.shadowRoot
+        .querySelector('[data-choice-value="api"]')
+        .getAttribute("aria-checked"),
+    ).is.equal("false");
+  });
 });