@schukai/monster 3.64.1 → 3.65.0

package/source/components/form/field-set.mjs

@@ -0,0 +1,300 @@
+/**
+ * Copyright © schukai GmbH and all contributing authors, {{copyRightYear}}. 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 schukai GmbH.
+ */
+
+import { instanceSymbol } from "../../constants.mjs";
+import { addAttributeToken } from "../../dom/attributes.mjs";
+import {
+	ATTRIBUTE_ERRORMESSAGE,
+	ATTRIBUTE_ROLE,
+} from "../../dom/constants.mjs";
+import { CustomControl } from "../../dom/customcontrol.mjs";
+import {
+	assembleMethodSymbol,
+	registerCustomElement,
+} from "../../dom/customelement.mjs";
+import { findTargetElementFromEvent } from "../../dom/events.mjs";
+import { isFunction } from "../../types/is.mjs";
+import { FieldSetStyleSheet } from "./stylesheet/field-set.mjs";
+import { fireCustomEvent } from "../../dom/events.mjs";
+import "../layout/collapse.mjs";
+
+export { FieldSet };
+
+/**
+ * @private
+ * @type {symbol}
+ */
+export const fieldSetElementSymbol = Symbol("fieldSetElement");
+
+/**
+ * This CustomControl creates a FieldSet element with a variety of options.
+ *
+ * <img src="./images/field-set.png">
+ *
+ * You can create this control either by specifying the HTML tag <monster-field-set />` directly in the HTML or using
+ * Javascript via the `document.createElement('monster-field-set');` method.
+ *
+ * ```html
+ * <monster-field-set></monster-field-set>
+ * ```
+ *
+ * Or you can create this CustomControl directly in Javascript:
+ *
+ * ```js
+ * import {FieldSet} from '@schukai/monster/source/components/form/field-set.mjs';
+ * document.createElement('monster-field-set');
+ * ```
+ *
+ * @externalExample ../..../example/components/form/field-set.mjs
+ * @startuml field-set.png
+ * skinparam monochrome true
+ * skinparam shadowing false
+ * HTMLElement <|-- CustomElement
+ * CustomElement <|-- CustomControl
+ * CustomControl <|-- FieldSet
+ * @enduml
+ *
+ * @since 3.65.0
+ * @copyright schukai GmbH
+ * @memberOf Monster.Components.Form
+ * @summary A simple FieldSet
+ */
+class FieldSet extends CustomControl {
+	/**
+	 * This method is called by the `instanceof` operator.
+	 * @returns {symbol}
+	 */
+	static get [instanceSymbol]() {
+		return Symbol.for("@schukai/monster/components/form/fieldset@@instance");
+	}
+
+	/**
+	 *
+	 * @return {Components.Form.FieldSet
+	 */
+	[assembleMethodSymbol]() {
+		super[assembleMethodSymbol]();
+		initControlReferences.call(this);
+		initEventHandler.call(this);
+		return this;
+	}
+
+	/**
+	 * To set the options via the html tag the attribute `data-monster-options` must be used.
+	 * @see {@link https://monsterjs.org/en/doc/#configurate-a-monster-control}
+	 *
+	 * The individual configuration values can be found in the table.
+	 *
+	 * @property {Object} templates Template definitions
+	 * @property {string} templates.main Main template
+	 * @property {Object} labels Label definitions
+	 * @property {Object} actions Callbacks
+	 * @property {string} actions.click="throw Error" Callback when clicked
+	 * @property {Object} features Features
+	 * @property {Object} classes CSS classes
+	 * @property {boolean} disabled=false Disabled state
+	 */
+	get defaults() {
+		return Object.assign({}, super.defaults, {
+			templates: {
+				main: getTemplate(),
+			},
+			labels: {
+			},
+			classes: {
+			},
+			disabled: false,
+			features: {
+            },
+			actions: {
+				click: () => {
+					throw new Error("the click action is not defined");
+				},
+			},
+            value: null
+		});
+	}
+
+	/**
+	 *
+	 * @return {string}
+	 */
+	static getTag() {
+		return "monster-field-set";
+	}
+
+	/**
+	 *
+	 * @return {Array<CSSStyleSheet>}
+	 */
+	static getCSSStyleSheet() {
+		return [FieldSetStyleSheet];
+	}
+	
+	
+	/**
+	 * The FieldSet.click() method simulates a click on the internal element.
+	 *
+	 * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/click}
+	 */
+	click() {
+		if (this.getOption("disabled") === true) {
+			return;
+		}
+
+		if (
+			this[fieldSetElementSymbol] &&
+			isFunction(this[fieldSetElementSymbol].click)
+		) {
+			this[fieldSetElementSymbol].click();
+		}
+	}
+
+	/**
+	 * The Button.focus() method sets focus on the internal element.
+	 *
+	 * @param {Object} options
+	 * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus}
+	 */
+	focus(options) {
+		if (this.getOption("disabled") === true) {
+			return;
+		}
+
+		if (
+			this[fieldSetElementSymbol] &&
+			isFunction(this[fieldSetElementSymbol].focus)
+		) {
+			this[fieldSetElementSymbol].focus(options);
+		}
+	}
+
+	/**
+	 * The Button.blur() method removes focus from the internal element.
+	 */
+	blur() {
+		if (
+			this[fieldSetElementSymbol] &&
+			isFunction(this[fieldSetElementSymbol].blur)
+		) {
+			this[fieldSetElementSymbol].blur();
+		}
+	}
+	
+	/**
+	 * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/attachInternals}
+	 * @return {boolean}
+	 */
+	static get formAssociated() {
+		return true;
+	}
+	
+	/**
+	 * The current value of the form control.
+	 *
+	 * ```js
+	 * e = document.querySelector('monster-field-set');
+	 * console.log(e.value)
+	 * ```
+	 *
+	 * @property {string}
+	 */
+	get value() {
+		return this.getOption("value");
+	}
+
+	/**
+	 * Set value of the form control.
+	 *
+	 * ```
+	 * e = document.querySelector('monster-field-set');
+	 * e.value=1
+	 * ```
+	 *
+	 * @property {string} value
+	 * @throws {Error} unsupported type
+	 */
+	set value(value) { 
+		this.setOption("value", value);
+		try {
+			this?.setFormValue(this.value);
+		} catch (e) {
+			addAttributeToken(this, ATTRIBUTE_ERRORMESSAGE, e.message);
+		}
+	}
+	
+
+}
+
+/**
+ * @private
+ * @return {initEventHandler}
+ * @fires Monster.Components.Form.event:monster-field-set-clicked
+ */
+function initEventHandler() {
+	const self = this;
+	const element = this[fieldSetElementSymbol];
+
+	const type = "click";
+
+	element.addEventListener(type, function (event) {
+		const callback = self.getOption("actions.click");
+
+		fireCustomEvent(self, "monster-field-set-clicked", {
+			element: self,
+		});
+
+		if (!isFunction(callback)) {
+			return;
+		}
+
+		const element = findTargetElementFromEvent(
+			event,
+			ATTRIBUTE_ROLE,
+			"control",
+		);
+
+		if (!(element instanceof Node && self.hasNode(element))) {
+			return;
+		}
+
+		callback.call(self, event);
+	});
+
+	return this;
+}
+
+/**
+ * @private
+ */
+function initControlReferences() {
+	this[fieldSetElementSymbol] = this.shadowRoot.querySelector(
+		`[${ATTRIBUTE_ROLE}="control"]`,
+	);
+}
+
+/**
+ * @private
+ * @return {string}
+ */
+function getTemplate() {
+	// language=HTML
+	return `
+        <div data-monster-role="control" part="control">
+			<monster-collapse>
+			<slot></slot>
+			</monster-collapse>
+        </div>`;
+}
+
+
+registerCustomElement(FieldSet);