@schukai/monster 3.48.0 → 3.50.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@schukai/monster",
-  "version": "3.48.0",
+  "version": "3.50.0",
   "description": "Monster is a simple library for creating fast, robust and lightweight websites.",
   "keywords": [
     "framework",

package/source/data/datasource/server/restapi/data-fetch-error.mjs

@@ -27,7 +27,7 @@ class DataFetchError extends Error {
     constructor(message, response) {
         super(message);
         this[internalSymbol] = {
-            response: response
+            response: response,
         };
     }
 
@@ -46,5 +46,4 @@ class DataFetchError extends Error {
     getResponse() {
         return this[internalSymbol]["response"];
     }
-
 }

package/source/data/datasource/server/restapi.mjs

@@ -5,13 +5,13 @@
  * License text available at https://www.gnu.org/licenses/agpl-3.0.en.html
  */
 
-import {internalSymbol, instanceSymbol} from "../../../constants.mjs";
-import {isObject, isFunction} from "../../../types/is.mjs";
-import {Server} from "../server.mjs";
-import {WriteError} from "./restapi/writeerror.mjs";
-import {DataFetchError} from "./restapi/data-fetch-error.mjs";
+import { internalSymbol, instanceSymbol } from "../../../constants.mjs";
+import { isObject, isFunction } from "../../../types/is.mjs";
+import { Server } from "../server.mjs";
+import { WriteError } from "./restapi/writeerror.mjs";
+import { DataFetchError } from "./restapi/data-fetch-error.mjs";
 
-export {RestAPI};
+export { RestAPI };
 
 /**
  * @type {symbol}
@@ -189,7 +189,10 @@ function fetchData(init, key, callback) {
             const acceptedStatus = self.getOption(`${key}.acceptedStatus`, [200]);
 
             if (acceptedStatus.indexOf(resp.status) === -1) {
-                throw new DataFetchError(`the response does not contain a accepted status (actual: ${resp.status}).`, response);
+                throw new DataFetchError(
+                    `the response does not contain a accepted status (actual: ${resp.status}).`,
+                    response,
+                );
             }
 
             return resp.text();

package/source/data/transformer.mjs

@@ -673,6 +673,24 @@ function transform(value) {
                 throw new Error(`unsupported locale or missing format (${e.message})`);
             }
 
+        case "datetimeformat":
+            date = new Date(value);
+            if (isNaN(date.getTime())) {
+                throw new Error("invalid date");
+            }
+
+            const options = {
+                dateStyle: args.shift() || "medium",
+                timeStyle: args.shift() || "medium",
+            };
+
+            try {
+                locale = getLocaleOfDocument();
+                return new Intl.DateTimeFormat(locale, options).format(date);
+            } catch (e) {
+                throw new Error(`unsupported locale or missing format (${e.message})`);
+            }
+
         case "datetime":
             date = new Date(value);
             if (isNaN(date.getTime())) {

package/source/dom/constants.mjs

@@ -61,7 +61,7 @@ export {
     customElementUpdaterLinkSymbol,
     initControlCallbackName,
     ATTRIBUTE_SCRIPT_HOST,
-    ATTRIBUTE_OPTION_CALLBACK
+    ATTRIBUTE_INIT_CALLBACK,
 };
 
 /**
@@ -117,7 +117,7 @@ const ATTRIBUTE_OPTIONS_SELECTOR = `${ATTRIBUTE_PREFIX}options-selector`;
  * @since 3.48.0
  * @type {string}
  */
-const ATTRIBUTE_OPTION_CALLBACK = `${ATTRIBUTE_PREFIX}option-callback`;
+const ATTRIBUTE_INIT_CALLBACK = `${ATTRIBUTE_PREFIX}init-callback`;
 
 /**
  * This is the name of the callback to pass the callback to a control

package/source/dom/customcontrol.mjs

@@ -5,12 +5,13 @@
  * License text available at https://www.gnu.org/licenses/agpl-3.0.en.html
  */
 
-import {extend} from "../data/extend.mjs";
-import {ATTRIBUTE_VALUE} from "./constants.mjs";
-import {CustomElement, attributeObserverSymbol} from "./customelement.mjs";
-import {instanceSymbol} from "../constants.mjs";
+import { extend } from "../data/extend.mjs";
+import { addAttributeToken } from "./attributes.mjs";
+import { ATTRIBUTE_ERRORMESSAGE } from "./constants.mjs";
+import { CustomElement, attributeObserverSymbol } from "./customelement.mjs";
+import { instanceSymbol } from "../constants.mjs";
 
-export {CustomControl};
+export { CustomControl };
 
 /**
  * @private
@@ -19,54 +20,61 @@ export {CustomControl};
 const attachedInternalSymbol = Symbol("attachedInternal");
 
 /**
- * To define a new HTML control we need the power of CustomElement
+ * This is a base class for creating custom controls using the power of CustomElement.
  *
- * IMPORTANT: after defining a `CustomElement`, the `registerCustomElement` method must be called
- * with the new class name. only then will the tag defined via the `getTag` method be made known to the DOM.
+ * After defining a `CustomElement`, the `registerCustomElement` method must be called with the new class name. Only then
+ * will the tag defined via the `getTag` method be made known to the DOM.
  *
  * <img src="./images/customcontrol-class.png">
  *
- * This control uses `attachInternals()` to integrate the control into a form.
- * If the target environment does not support this method, the [polyfill](https://www.npmjs.com/package/element-internals-polyfill ) can be used.
+ * This control uses `attachInternals()` to integrate the control into a form. If the target environment does not support
+ * this method, the [polyfill](https://www.npmjs.com/package/element-internals-polyfill) can be used.
  *
- * You can create the object via the function `document.createElement()`.
+ * You can create the object using the function `document.createElement()`.
  *
- * @startuml customcontrol-class.png
- * skinparam monochrome true
- * skinparam shadowing false
- * HTMLElement <|-- CustomElement
- * CustomElement <|-- CustomControl
- * @enduml
+ * This control uses `attachInternals()` to integrate the control into a form. If the target environment does not support
+ * this method, the Polyfill for attachInternals() can be used: {@link https://www.npmjs.com/package/element-internals-polyfill|element-internals-polyfill}.
  *
- * @summary A base class for customcontrols based on CustomElement
- * @see {@link https://www.npmjs.com/package/element-internals-polyfill}
- * @see {@link https://github.com/WICG/webcomponents}
- * @see {@link https://html.spec.whatwg.org/multipage/custom-elements.html#custom-elements}
- * @see {@link https://html.spec.whatwg.org/dev/custom-elements.html#custom-element-reactions}
+ * Learn more about WICG Web Components: {@link https://github.com/WICG/webcomponents|WICG Web Components}.
+ *
+ * Read the HTML specification for Custom Elements: {@link https://html.spec.whatwg.org/multipage/custom-elements.html#custom-elements|Custom Elements}.
+ *
+ * Read the HTML specification for Custom Element Reactions: {@link https://html.spec.whatwg.org/dev/custom-elements.html#custom-element-reactions|Custom Element Reactions}.
+ *
+ * @summary A base class for custom controls based on CustomElement.
+ * @copyright schukai GmbH
  * @license AGPLv3
  * @since 1.14.0
- * @copyright schukai GmbH
  * @memberOf Monster.DOM
+ * @extends Monster.DOM.CustomElement
  */
 class CustomControl extends CustomElement {
     /**
-     * IMPORTANT: CustomControls instances are not created via the constructor, but either via a tag in the HTML or via <code>document.createElement()</code>.
+     * The constructor method of CustomControl, which is called when creating a new instance.
+     * It checks whether the element supports `attachInternals()` and initializes an internal form-associated element
+     * if supported. Additionally, it initializes a MutationObserver to watch for attribute changes.
      *
+     * See the links below for more information:
+     * {@link https://html.spec.whatwg.org/multipage/custom-elements.html#dom-customelementregistry-define|CustomElementRegistry.define()}
+     * {@link https://html.spec.whatwg.org/multipage/custom-elements.html#dom-customelementregistry-get|CustomElementRegistry.get()}
+     * and {@link https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals|ElementInternals}
+     *
+     * @inheritdoc
      * @throws {Error} the ElementInternals is not supported and a polyfill is necessary
-     * @summary create new Instance
+     * @since 1.7.0
      */
     constructor() {
         super();
 
+        // check if element supports `attachInternals()`
         if (typeof this["attachInternals"] === "function") {
-            /**
-             * currently only supported by chrome
-             * @property {Object}
-             * @private
-             */
             this[attachedInternalSymbol] = this.attachInternals();
+        } else {
+            // `attachInternals()` is not supported, so a polyfill is necessary
+            throw Error("the ElementInternals is not supported and a polyfill is necessary");
         }
 
+        // initialize a MutationObserver to watch for attribute changes
         initObserver.call(this);
     }
 
@@ -90,40 +98,27 @@ class CustomControl extends CustomElement {
     }
 
     /**
-     * Adding a static formAssociated property, with a true value, makes an autonomous custom element a form-associated custom element.
+     * Adding a static `formAssociated` property, with a true value, makes an autonomous custom element a form-associated custom element.
      *
-     * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/attachInternals}
-     * @see {@link https://html.spec.whatwg.org/multipage/custom-elements.html#custom-elements-face-example}
+     * @see [attachInternals()]{@link https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/attachInternals}
+     * @see [Custom Elements Face Example]{@link https://html.spec.whatwg.org/multipage/custom-elements.html#custom-elements-face-example}
      * @since 1.14.0
      * @return {boolean}
      */
-    static formAssociated = true
+    static formAssociated = true;
 
     /**
-     * Derived classes can override and extend this method as follows.
-     *
-     * ```
-     * get defaults() {
-     *    return extends{}, super.defaults, {
-     *        myValue:true
-     *    });
-     * }
-     * ```
-     *
-     * @see {@link https://html.spec.whatwg.org/multipage/custom-elements.html#custom-elements-face-example}
-     * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/attachInternals}
-     * @return {object}
+     * @inheritdoc
      * @since 1.14.0
-     */
+     **/
     get defaults() {
-        return extend({
-        }, super.defaults);
+        return extend({}, super.defaults);
     }
 
     /**
      * Must be overridden by a derived class and return the value of the control.
      *
-     * This is a method of [internal api](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals)
+     * This is a method of [internal API](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals), which is a part of the web standard for custom elements.
      *
      * @since 1.14.0
      * @throws {Error} the value getter must be overwritten by the derived class
@@ -133,11 +128,11 @@ class CustomControl extends CustomElement {
     }
 
     /**
-     * Must be overridden by a derived class and return the value of the control.
+     * Must be overridden by a derived class and set the value of the control.
      *
-     * This is a method of [internal api](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals)
+     * This is a method of [internal API](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals), which is a part of the web standard for custom elements.
      *
-     * @param {*} value
+     * @param {*} value The value to set.
      * @since 1.14.0
      * @throws {Error} the value setter must be overwritten by the derived class
      */
@@ -180,8 +175,8 @@ class CustomControl extends CustomElement {
      *
      * @return {ValidityState}
      * @throws {Error} the ElementInternals is not supported and a polyfill is necessary
-     * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/ValidityState}
-     * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/validity}
+     * @see [ValidityState]{@link https://developer.mozilla.org/en-US/docs/Web/API/ValidityState}
+     * @see [validity]{@link https://developer.mozilla.org/en-US/docs/Web/API/validity}
      */
     get validity() {
         return getInternal.call(this)?.validity;
@@ -214,7 +209,7 @@ class CustomControl extends CustomElement {
     /**
      * This is a method of [internal api](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals)
      *
-     * @return {CustomStateSet}
+     * @return {boolean}
      * @since 1.14.0
      * @see https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/states
      * @throws {Error} the ElementInternals is not supported and a polyfill is necessary
@@ -301,12 +296,15 @@ class CustomControl extends CustomElement {
     }
 
     /**
-     * @param {string} form
+     * Sets the `form` attribute of the custom control to the `id` of the passed form element.
+     * If no form element is passed, removes the `form` attribute.
+     *
+     * @param {HTMLFormElement} form - The form element to associate with the control
      */
     formAssociatedCallback(form) {
         if (form) {
-            if(form.id) {
-                this.setAttribute("form", form.id);    
+            if (form.id) {
+                this.setAttribute("form", form.id);
             }
         } else {
             this.removeAttribute("form");
@@ -314,7 +312,9 @@ class CustomControl extends CustomElement {
     }
 
     /**
-     * @param {string} disabled
+     * Sets or removes the `disabled` attribute of the custom control based on the passed value.
+     *
+     * @param {boolean} disabled - Whether or not the control should be disabled
      */
     formDisabledCallback(disabled) {
         if (disabled) {
@@ -328,17 +328,14 @@ class CustomControl extends CustomElement {
      * @param {string} state
      * @param {string} mode
      */
-    formStateRestoreCallback(state, mode) {
-        
-    }
+    formStateRestoreCallback(state, mode) {}
 
     /**
      *
      */
     formResetCallback() {
-       this.value = "";
+        this.value = "";
     }
-
 }
 
 /**