@schukai/monster 3.51.5 → 3.52.0

package/source/components/form/popper-button.mjs

@@ -0,0 +1,435 @@
+/**
+ * Copyright schukai GmbH and contributors 2023. All Rights Reserved.
+ * Node module: @schukai/monster
+ * This file is licensed under the AGPLv3 License.
+ * License text available at https://www.gnu.org/licenses/agpl-3.0.en.html
+ */
+import { instanceSymbol } from "../../constants.mjs";
+import { addAttributeToken } from "../../dom/attributes.mjs";
+import {
+	ATTRIBUTE_ERRORMESSAGE,
+	ATTRIBUTE_ROLE,
+} from "../../dom/constants.mjs";
+import {
+	assembleMethodSymbol,
+	registerCustomElement,
+} from "../../dom/customelement.mjs";
+import { getDocument } from "../../dom/util.mjs";
+import { isFunction } from "../../types/is.mjs";
+import { DeadMansSwitch } from "../../util/deadmansswitch.mjs";
+import { Popper } from "./popper.mjs";
+import { STYLE_DISPLAY_MODE_BLOCK } from "./constants.mjs";
+import { PopperButtonStyleSheet } from "./stylesheet/popper-button.mjs";
+import { positionPopper } from "./util/floating-ui.mjs";
+import "./button.mjs";
+
+export { PopperButton };
+
+/**
+ * @private
+ * @type {symbol}
+ */
+const timerCallbackSymbol = Symbol("timerCallback");
+
+/**
+ * local symbol
+ * @private
+ * @type {symbol}
+ */
+const resizeObserverSymbol = Symbol("resizeObserver");
+
+/**
+ * local symbol
+ * @private
+ * @type {symbol}
+ */
+const closeEventHandler = Symbol("closeEventHandler");
+
+/**
+ * @private
+ * @type {symbol}
+ */
+const controlElementSymbol = Symbol("controlElement");
+
+/**
+ * @private
+ * @type {symbol}
+ */
+const buttonElementSymbol = Symbol("buttonElement");
+
+/**
+ * local symbol
+ * @private
+ * @type {symbol}
+ */
+const popperElementSymbol = Symbol("popperElement");
+
+/**
+ * local symbol
+ * @private
+ * @type {symbol}
+ */
+const arrowElementSymbol = Symbol("arrowElement");
+
+/**
+ * This action callback executes the actions when a button is clicked.
+ *
+ * @callback Monster.Components.Form~exampleActionCallback
+ * @param {Event} e Event
+ * @memberOf Monster.Components.Form
+ * @this {CustomControl}
+ */
+
+/**
+ * The PopperButton is a button that opens a popper element.
+ *
+ * <img src="./images/popper-button.png">
+ *
+ * Dependencies: the system uses functions of the [monsterjs](https://monsterjs.org/) library
+ * as well as [pooperjs](https://popper.js.org/docs/v2/).
+ *
+ * You can create this control either by specifying the HTML tag <monster-popper-button />` directly in the HTML or using
+ * Javascript via the `document.createElement('monster-popper-button');` method.
+ *
+ * ```html
+ * <monster-popper-button></monster-popper-button>
+ * ```
+ *
+ * Or you can create this CustomControl directly in Javascript:
+ *
+ * ```js
+ * import {PopperButton} from '@schukai/component-form/source/popper-button.js';
+ * document.createElement('monster-popper-button');
+ * ```
+ *
+ * The `data-monster-option-classes-button` attribute can be used to change the CSS class of the button.
+ *
+ * @startuml popper-button.png
+ * skinparam monochrome true
+ * skinparam shadowing false
+ * HTMLElement <|-- CustomElement
+ * CustomElement <|-- CustomControl
+ * CustomControl <|-- Popper
+ * Popper <|-- PopperButton
+ * @enduml
+ *
+ * @since 1.5.0
+ * @copyright schukai GmbH
+ * @memberOf Monster.Components.Form
+ * @summary A popper button
+ */
+class PopperButton extends Popper {
+	/**
+	 * This method is called by the `instanceof` operator.
+	 * @returns {symbol}
+	 * @since 2.1.0
+	 */
+	static get [instanceSymbol]() {
+		return Symbol.for("@schukai/component-form/popper-button@@instance");
+	}
+
+	/**
+	 * 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 - The templates for the control.
+	 * @property {string} templates.main - The main template.
+	 * @property {object} labels - The labels for the control.
+	 * @property {string} labels.button - The label for the button.
+	 * @property {string} content - The content of the popper.
+	 * @property {object} popper - The popper options.
+	 * @extends {Button.defaults}
+	 */
+	get defaults() {;
+
+		return Object.assign({}, super.defaults, {
+			templates: {
+				main: getTemplate(),
+			},
+			actions: {
+				click: (e) => {
+					this.toggleDialog();
+				},
+			},
+			classes: {
+				button: "monster-button",
+			},
+			labels: {
+				button: '<slot name="button"></slot>',
+			},
+			mode: "click",
+			value: null,
+		});
+	}
+
+	/**
+	 *
+	 * @return {Monster.Components.Form.PopperButton}
+	 */
+	[assembleMethodSymbol]() {
+		super[assembleMethodSymbol]();;
+		initControlReferences.call(this);
+		initEventhandler.call(this);
+
+		return this;
+	}
+
+	/**
+	 * @return {string}
+	 */
+	static getTag() {
+		return "monster-popper-button";
+	}
+
+	/**
+	 * @return {CSSStyleSheet[]}
+	 */
+	static getCSSStyleSheet() {
+		const styles = super.getCSSStyleSheet();
+		styles.push(PopperButtonStyleSheet);
+		return styles;
+	}
+
+	/**
+	 * @return {void}
+	 */
+	connectedCallback() {
+		super.connectedCallback();
+
+		const document = getDocument();;
+
+		for (const [, type] of Object.entries(["click", "touch"])) {
+			// close on outside ui-events
+			document.addEventListener(type, this[closeEventHandler]);
+		}
+
+		updatePopper.call(this);
+		attachResizeObserver.call(this);
+	}
+
+	/**
+	 * @return {void}
+	 */
+	disconnectedCallback() {
+		super.disconnectedCallback();
+
+		// close on outside ui-events
+		for (const [, type] of Object.entries(["click", "touch"])) {
+			document.removeEventListener(type, this[closeEventHandler]);
+		}
+
+		disconnectResizeObserver.call(this);
+	}
+
+	/**
+	 * The Button.click() method simulates a click on the internal button element.
+	 *
+	 * @since 3.27.0
+	 * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/click}
+	 */
+	click() {
+		if (this.getOption("disabled") === true) {
+			return;
+		}
+
+		if (
+			this[buttonElementSymbol] &&
+			isFunction(this[buttonElementSymbol].click)
+		) {
+			this[buttonElementSymbol].click();
+		}
+	}
+
+	/**
+	 * The Button.focus() method sets focus on the internal button element.
+	 *
+	 * @since 3.27.0
+	 * @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[buttonElementSymbol] &&
+			isFunction(this[buttonElementSymbol].focus)
+		) {
+			this[buttonElementSymbol].focus(options);
+		}
+	}
+
+	/**
+	 * The Button.blur() method removes focus from the internal button element.
+	 */
+	blur() {
+		if (
+			this[buttonElementSymbol] &&
+			isFunction(this[buttonElementSymbol].blur)
+		) {
+			this[buttonElementSymbol].blur();
+		}
+	}
+
+	/**
+	 * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/attachInternals}
+	 * @return {boolean}
+	 */
+	static get formAssociated() {
+		return true;
+	}
+
+	/**
+	 * The current selection of the Select
+	 *
+	 * ```
+	 * e = document.querySelector('monster-select');
+	 * console.log(e.value)
+	 * // ↦ 1
+	 * // ↦ ['1','2']
+	 * ```
+	 *
+	 * @property {string|array}
+	 */
+	get value() {
+		return this.getOption("value");
+	}
+
+	/**
+	 * Set selection
+	 *
+	 * ```
+	 * e = document.querySelector('monster-select');
+	 * e.value=1
+	 * ```
+	 *
+	 * @property {string|array} value
+	 * @since 1.2.0
+	 * @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}
+ */
+function initEventhandler() {;
+
+	this[closeEventHandler] = (event) => {
+		const path = event.composedPath();
+
+		for (const [, element] of Object.entries(path)) {
+			if (element === this) {
+				return;
+			}
+		}
+		this.hideDialog();
+	};
+
+	return this;
+}
+
+/**
+ * @private
+ */
+function attachResizeObserver() {;
+
+	// against flickering
+	this[resizeObserverSymbol] = new ResizeObserver(() => {
+		if (this[timerCallbackSymbol] instanceof DeadMansSwitch) {
+			try {
+				this[timerCallbackSymbol].touch();
+				return;
+			} catch (e) {
+				delete this[timerCallbackSymbol];
+			}
+		}
+
+		this[timerCallbackSymbol] = new DeadMansSwitch(200, () => {
+			updatePopper.call(this);
+		});
+	});
+
+	this[resizeObserverSymbol].observe(this.parentElement);
+}
+
+function disconnectResizeObserver() {;
+	if (this[resizeObserverSymbol] instanceof ResizeObserver) {
+		this[resizeObserverSymbol].disconnect();
+	}
+}
+
+/**
+ * @private
+ */
+function updatePopper() {;
+
+	if (this[popperElementSymbol].style.display !== STYLE_DISPLAY_MODE_BLOCK) {
+		return;
+	}
+
+	if (this.getOption("disabled", false) === true) {
+		return;
+	}
+
+	positionPopper.call(
+		this,
+		this[controlElementSymbol],
+		this[popperElementSymbol],
+		this.getOption("popper", {}),
+	);
+}
+
+/**
+ * @private
+ * @return {Select}
+ */
+function initControlReferences() {
+	this[controlElementSymbol] = this.shadowRoot.querySelector(
+		`[${ATTRIBUTE_ROLE}=control]`,
+	);
+	this[buttonElementSymbol] = this.shadowRoot.querySelector(
+		`[${ATTRIBUTE_ROLE}=button]`,
+	);
+	this[popperElementSymbol] = this.shadowRoot.querySelector(
+		`[${ATTRIBUTE_ROLE}=popper]`,
+	);
+	this[arrowElementSymbol] = this.shadowRoot.querySelector(
+		`[${ATTRIBUTE_ROLE}=arrow]`,
+	);
+}
+
+/**
+ * @private
+ * @return {string}
+ */
+function getTemplate() {
+	// language=HTML
+	return `
+        <div data-monster-role="control" part="control">
+            <button data-monster-attributes="disabled path:disabled | if:true, class path:classes.button"
+                    data-monster-role="button"
+                    part="button"
+                    data-monster-replace="path:labels.button"></button>
+
+            <div data-monster-role="popper" part="popper" tabindex="-1" class="monster-color-primary-1">
+                <div data-monster-role="arrow"></div>
+                <div part="content" class="flex" data-monster-replace="path:content">
+                </div>
+            </div>
+        </div>
+    `;
+}
+
+registerCustomElement(PopperButton);