@schukai/monster 1.12.0 → 1.15.0

package/source/dom/customcontrol.js

@@ -0,0 +1,301 @@
+'use strict';
+
+/**
+ * @author schukai GmbH
+ */
+import {Monster, assignToNamespace} from '../namespace.js';
+import {extend} from "../data/extend.js";
+import { CustomElement} from "./customelement.js";
+
+
+/**
+ * @private
+ * @type {symbol}
+ */
+const internalSymbol = Symbol('internalSymbol');
+
+/**
+ * To define a new HTML control we need 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.
+ *
+ * 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 monster namespace `new Monster.DOM.CustomControl()`.
+ *
+ * ```
+ * <script type="module">
+ * import {Monster} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.15.0/dist/modules/dom/customcontrol.js';
+ * console.log(new Monster.DOM.CustomControl())
+ * </script>
+ * ```
+ *
+ * Alternatively, you can also integrate this function individually.
+ *
+ * ```
+ * <script type="module">
+ * import {CustomControl} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.15.0/dist/modules/dom/customcontrol.js';
+ * console.log(new CustomControl())
+ * </script>
+ * ```
+ *
+ * @see https://www.npmjs.com/package/element-internals-polyfill
+ * @see https://github.com/WICG/webcomponents
+ * @see https://html.spec.whatwg.org/multipage/custom-elements.html#custom-elements
+ * @since 1.14.0
+ * @copyright schukai GmbH
+ * @memberOf Monster/DOM
+ */
+class CustomControl extends CustomElement {
+
+    /**
+     *
+     * @throws {Error} the ElementInternals is not supported and a polyfill is necessary
+     */
+    constructor() {
+        super();
+
+        if (typeof this['attachInternals'] === 'function') {
+            // currently only supported by chrome
+            this[internalSymbol] = this.attachInternals();
+        }
+
+    }
+
+    /**
+     * | option         | description                     |
+     * |----------------|---------------------------------|
+     * |                |                                 |
+     *
+     * Derived classes can override and extend this method as follows.
+     *
+     * ```
+     * get defaults() {
+     *    return extends{}, super.defaults, {
+     *        myValue:true
+     *    });
+     * }
+     * ```
+     *
+     * @see https://html.spec.whatwg.org/multipage/custom-elements.html#custom-elements-face-example
+     * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/attachInternals
+     * @return {object}
+     * @since 1.14.0
+     */
+    get defaults() {
+        return extend({}, super.defaults);
+    }
+
+    /**
+     *
+     * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/attachInternals
+     * @since 1.14.0
+     * @return {boolean}
+     */
+    static get formAssociated() {
+        return true;
+    }
+
+    /**
+     * 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)
+     *
+     * @since 1.14.0
+     * @throws {Error} the value getter must be overwritten by the derived class
+     */
+    get value() {
+        throw Error('the value getter must be overwritten by the derived class');
+    }
+
+    /**
+     * 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)
+     *
+     * @param {*} value
+     * @since 1.14.0
+     * @throws {Error} the value setter must be overwritten by the derived class
+     */
+    set value(value) {
+        throw Error('the value setter must be overwritten by the derived class');
+    }
+
+    /**
+     * This is a method of [internal api](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals)
+     *
+     * ```
+     * // Use the control's name as the base name for submitted data
+     * const n = this.getAttribute('name');
+     * const entries = new FormData();
+     * entries.append(n + '-first-name', this.firstName_);
+     * entries.append(n + '-last-name', this.lastName_);
+     * this.setFormValue(entries);
+     * ```
+     *
+     * @param {File|string|FormData} value
+     * @param {File|string|FormData} state
+     * @since 1.14.0
+     * @return {undefined}
+     * @throws {DOMException} NotSupportedError
+     * @throws {Error} the ElementInternals is not supported and a polyfill is necessary
+     * @see https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/setFormValue
+     */
+    setFormValue(value, state) {
+        getInternal.call(this).setFormValue(value, state);
+    }
+
+    /**
+     *
+     * @param {object} flags
+     * @param {string|undefined} message
+     * @param {HTMLElement} anchor
+     * @see https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/setValidity
+     * @since 1.14.0
+     * @return {undefined}
+     * @throws {DOMException} NotSupportedError
+     * @throws {Error} the ElementInternals is not supported and a polyfill is necessary
+     */
+    setValidity(flags, message, anchor) {
+        getInternal.call(this).setValidity(flags, message, anchor);
+    }
+
+
+    /**
+     * This is a method of [internal api](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals)
+     *
+     * @see https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/checkValidity
+     * @since 1.14.0
+     * @return {boolean}
+     * @throws {DOMException} NotSupportedError
+     * @throws {Error} the ElementInternals is not supported and a polyfill is necessary
+     */
+    checkValidity() {
+        return getInternal.call(this)?.checkValidity();
+    }
+
+
+    /**
+     * This is a method of [internal api](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals)
+     *
+     * @return {boolean}
+     * @since 1.14.0
+     * @see https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/reportValidity
+     * @throws {Error} the ElementInternals is not supported and a polyfill is necessary
+     * @throws {DOMException} NotSupportedError
+     */
+    reportValidity() {
+        return getInternal.call(this)?.reportValidity();
+    }
+
+    /**
+     * This is a method of [internal api](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals)
+     *
+     * @return {NodeList}
+     * @since 1.14.0
+     * @see https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/labels
+     * @throws {Error} the ElementInternals is not supported and a polyfill is necessary
+     */
+    get labels() {
+        return getInternal.call(this)?.labels;
+    }
+
+    /**
+     * This is a method of [internal api](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals)
+     *
+     * @return {string|null}
+     */
+    get name() {
+        return this.getAttribute('name');
+    }
+
+    /**
+     * This is a method of [internal api](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals)
+     *
+     * @return {string}
+     */
+    get type() {
+        return this.constructor.getTag();
+    }
+
+    /**
+     * This is a method of [internal api](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals)
+     *
+     * @return {ValidityState}
+     * @throws {Error} the ElementInternals is not supported and a polyfill is necessary
+     * @see https://developer.mozilla.org/en-US/docs/Web/API/ValidityState
+     * @see https://developer.mozilla.org/en-US/docs/Web/API/validity
+     */
+    get validity() {
+        return getInternal.call(this)?.validity;
+    }
+
+    /**
+     * This is a method of [internal api](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals)
+     *
+     * @return {string}
+     * @since 1.14.0
+     * @see https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/validationMessage
+     * @throws {Error} the ElementInternals is not supported and a polyfill is necessary
+     */
+    get validationMessage() {
+        return getInternal.call(this)?.validationMessage;
+    }
+
+    /**
+     * This is a method of [internal api](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals)
+     *
+     * @return {boolean}
+     * @since 1.14.0
+     * @see https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/willValidate
+     * @throws {Error} the ElementInternals is not supported and a polyfill is necessary
+     */
+    get willValidate() {
+        return getInternal.call(this)?.willValidate;
+    }
+
+    /**
+     * This is a method of [internal api](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals)
+     *
+     * @return {CustomStateSet}
+     * @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
+     */
+    get states() {
+        return getInternal.call(this)?.states;
+    }
+
+    /**
+     * This is a method of [internal api](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals)
+     *
+     * @return {HTMLFontElement|null}
+     * @since 1.14.0
+     * @see https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals/form
+     * @throws {Error} the ElementInternals is not supported and a polyfill is necessary
+     */
+    get form() {
+        return getInternal.call(this)?.form;
+    }
+
+}
+
+/**
+ * @private
+ * @return {object}
+ * @throws {Error} the ElementInternals is not supported and a polyfill is necessary
+ */
+function getInternal() {
+    const self = this;
+
+    if (!(internalSymbol in this)) {
+        throw new Error('ElementInternals is not supported and a polyfill is necessary');
+    }
+
+    return this[internalSymbol];
+}
+
+assignToNamespace('Monster.DOM', CustomControl);
+export {Monster, CustomControl}

package/source/dom/customelement.js

@@ -3,23 +3,27 @@
 /**
  * @author schukai GmbH
  */
-
-import {Monster, Updater} from "./updater.js";
+import {Monster, assignToNamespace} from '../namespace.js';
+import {Observer} from "../types/observer.js";
+import {ProxyObserver} from "../types/proxyobserver.js";
+import { Updater} from "./updater.js";
 import {extend} from "../data/extend.js";
+import {clone} from "../util/clone.js";
 import {Pathfinder} from "../data/pathfinder.js";
-import {ATTRIBUTE_OPTIONS, OBJECTLINK_KEY_OPTIONS, OBJECTLINK_KEY_UPDATER} from "./constants.js";
+import {ATTRIBUTE_OPTIONS, OBJECTLINK_KEY_UPDATER} from "./constants.js";
 import {findDocumentTemplate, Template} from "./template.js";
-import {addToObjectLink, hasObjectLink} from "./attributes.js";
+import {addToObjectLink, getLinkedObjects, hasObjectLink} from "./attributes.js";
 import {getGlobalObject} from "../types/global.js";
 import {validateFunction, validateObject} from "../types/validate.js";
 import {isString} from "../types/is.js";
-import {getDocument} from "./util.js";
+import {PROPERTY_KEY_INTERNALDATA} from "../constants.js";
 
 /**
  * @private
  * @type {symbol}
  */
-const optionsSymbol = Symbol.for(OBJECTLINK_KEY_OPTIONS);
+const internalDataSymbol = Symbol.for(PROPERTY_KEY_INTERNALDATA);
+
 /**
  * @private
  * @type {symbol}
@@ -36,12 +40,6 @@ const initMethodSymbol = Symbol('initMethodSymbol');
  */
 const assembleMethodSymbol = Symbol('assembleMethodSymbol');
 
-/**
- * @private
- * @type {Document}
- */
-const document = getDocument();
-
 /**
  * To define a new HTML element we need the power of CustomElement
  *
@@ -52,7 +50,7 @@ const document = getDocument();
  *
  * ```
  * <script type="module">
- * import {CustomElement} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.12.0/dist/modules/dom/customelement.js';
+ * import {CustomElement} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.15.0/dist/modules/dom/customelement.js';
  * console.log(new Monster.DOM.CustomElement())
  * </script>
  * ```
@@ -61,7 +59,7 @@ const document = getDocument();
  *
  * ```
  * <script type="module">
- * import {CustomElement} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.12.0/dist/modules/dom/customelement.js';
+ * import {CustomElement} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.15.0/dist/modules/dom/customelement.js';
  * console.log(new CustomElement())
  * </script>
  * ```
@@ -159,15 +157,47 @@ class CustomElement extends HTMLElement {
      */
     constructor() {
         super();
-        this[optionsSymbol] = extend({}, this.defaults, getOptionsFromAttributes.call(this));
+        this[internalDataSymbol] = new ProxyObserver({'options': extend({}, this.defaults, getOptionsFromAttributes.call(this))});
+        initOptionObserver.call(this);
         this[initMethodSymbol]();
     }
 
+    /**
+     * attach a new observer
+     *
+     * @param {Observer} observer
+     * @returns {CustomElement}
+     */
+    attachObserver(observer) {
+        this[internalDataSymbol].attachObserver(observer)
+        return this;
+    }
+
+    /**
+     * detach a observer
+     *
+     * @param {Observer} observer
+     * @returns {CustomElement}
+     */
+    detachObserver(observer) {
+        this[internalDataSymbol].detachObserver(observer)
+        return this;
+    }
+
+    /**
+     * @param {Observer} observer
+     * @returns {ProxyObserver}
+     */
+    containsObserver(observer) {
+        return this[internalDataSymbol].containsObserver(observer)
+    }
+
     /**
      * | option         | description                                                                                                                                                                                                                                                                |
      * |----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
      * | shadowMode     | `open` Elements of the shadow root are accessible from JavaScript outside the root, for example using. `close` Denies access to the node(s) of a closed shadow root from JavaScript outside it                                                                             |
      * | delegatesFocus | A boolean that, when set to true, specifies behavior that mitigates custom element issues around focusability. When a non-focusable part of the shadow DOM is clicked, the first focusable part is given focus, and the shadow host is given any available :focus styling. |
+     * | templates.main | Main template                                                                                                                                                                                                                                                              |
      *
      * Derived classes can override and extend this method as follows.
      *
@@ -205,7 +235,7 @@ class CustomElement extends HTMLElement {
         let value;
 
         try {
-            value = new Pathfinder(this[optionsSymbol]).getVia(path);
+            value = new Pathfinder(this[internalDataSymbol].getRealSubject()['options']).getVia(path);
         } catch (e) {
 
         }
@@ -214,6 +244,38 @@ class CustomElement extends HTMLElement {
         return value;
     }
 
+    /**
+     * Set option and inform elements
+     *
+     * @param {string} path
+     * @param {*} value
+     * @return {CustomElement}
+     * @since 1.14.0
+     */
+    setOption(path, value) {
+        new Pathfinder(this[internalDataSymbol].getSubject()['options']).setVia(path, value);
+        //this[internalDataSymbol].notifyObservers();
+        return this;
+    }
+
+    /**
+     * @since 1.15.0
+     * @param {string|object} options
+     * @return {CustomElement}
+     */
+    setOptions(options) {
+
+        if (isString(options)) {
+            options = parseOptionsJSON(options)
+        }
+
+        const self = this;
+        extend(self[internalDataSymbol].getSubject()['options'], self.defaults, options);
+        //this[internalDataSymbol].notifyObservers();
+        
+        return self;
+    }
+
     /**
      *
      * @return {CustomElement}
@@ -253,8 +315,8 @@ class CustomElement extends HTMLElement {
         for (const [, element] of Object.entries(elements)) {
 
             if (!(element instanceof HTMLElement)) continue;
-
-            const u = new Updater(element, this[optionsSymbol])
+            if ((element instanceof HTMLTemplateElement)) continue;
+            const u = new Updater(element, clone(self[internalDataSymbol].getRealSubject()['options']))
             updater.add(u);
 
             u.run().then(() => {
@@ -263,7 +325,6 @@ class CustomElement extends HTMLElement {
 
         }
 
-
         return this;
     }
 
@@ -303,22 +364,39 @@ class CustomElement extends HTMLElement {
 
     }
 
+    /**
+     * This method determines which attributes are to be monitored by `attributeChangedCallback()`.
+     *
+     * @return {string[]}
+     * @since 1.15.0
+     */
+    static get observedAttributes() {
+        return [ATTRIBUTE_OPTIONS];
+    }
+
     /**
      * Called when an observed attribute has been added, removed, updated, or replaced. Also called for initial
-     * values when an element is created by the parser, or upgraded. Note: only attributes listed in the observedAttributes property will receive this callback.
+     * values when an element is created by the parser, or upgraded. Note: only attributes listed in the observedAttributes
+     * property will receive this callback.
      *
      * @param {string} attrName
      * @param {string} oldVal
      * @param {string} newVal
      * @return {void}
-     * @since 1.7.0
+     * @since 1.15.0
      */
     attributeChangedCallback(attrName, oldVal, newVal) {
+        const self = this;
+
+        if (attrName === ATTRIBUTE_OPTIONS) {
+            self.setOptions(newVal);
+        }
+
     }
 
     /**
      * There is no check on the name by this class. the developer is responsible for assigning an appropriate tag.
-     * if the name is not valid, registerCustomElement() will issue an erro
+     * if the name is not valid, registerCustomElement() will issue an error
      *
      * @link https://html.spec.whatwg.org/multipage/custom-elements.html#valid-custom-element-name
      * @return {string}
@@ -330,25 +408,25 @@ class CustomElement extends HTMLElement {
     }
 
     /**
-     * At this point a `CSSStyleSheet` object can be returned. If the environment does not 
+     * At this point a `CSSStyleSheet` object can be returned. If the environment does not
      * support a constructor, then an object can also be built using the following detour.
-     * 
+     *
      * If `undefined` is returned then the shadowRoot does not get a stylesheet.
      *
      * ```
      * const doc = document.implementation.createHTMLDocument('title');
-     * 
+     *
      * let style = doc.createElement("style");
      * style.innerHTML="p{color:red;}";
-     * 
+     *
      * // WebKit Hack
      * style.appendChild(document.createTextNode(""));
      * // Add the <style> element to the page
      * doc.head.appendChild(style);
      * return doc.styleSheets[0];
-     * ; 
+     * ;
      * ```
-     * 
+     *
      * @return {CSSStyleSheet|undefined}
      */
     static getCSSStyleSheet() {
@@ -357,6 +435,33 @@ class CustomElement extends HTMLElement {
 
 }
 
+/**
+ * @since 1.15.0
+ * @private
+ */
+function initOptionObserver() {
+    const self = this;
+
+    self.attachObserver(new Observer(function () {
+
+        // not initialised
+        if (!hasObjectLink(self, Symbol.for(OBJECTLINK_KEY_UPDATER))) {
+            return;
+        }
+                // inform every element
+        const updaters = getLinkedObjects(self, Symbol.for(OBJECTLINK_KEY_UPDATER));
+
+        for (const list of updaters) {
+            for (const updater of list) {
+                let d = clone(self[internalDataSymbol].getRealSubject()['options']);
+                Object.assign(updater.getSubject(), d);
+            }
+        }
+
+    }));
+
+}
+
 /**
  * @private
  * @return {object}
@@ -365,11 +470,24 @@ class CustomElement extends HTMLElement {
 function getOptionsFromAttributes() {
     if (this.hasAttribute(ATTRIBUTE_OPTIONS)) {
         try {
-            let obj = JSON.parse(this.getAttribute(ATTRIBUTE_OPTIONS))
+            return parseOptionsJSON(this.getAttribute(ATTRIBUTE_OPTIONS))
+        } catch (e) {
+            throw new Error('the options attribute ' + ATTRIBUTE_OPTIONS + ' does not contain a valid json definition (actual: ' + this.getAttribute(ATTRIBUTE_OPTIONS) + ').');
+        }
+    }
+
+    return {};
+}
+
+
+function parseOptionsJSON(data) {
+    if (isString(data)) {
+        try {
+            let obj = JSON.parse(data);
             validateObject(obj);
             return obj;
         } catch (e) {
-            throw new Error('the options attribute ' + ATTRIBUTE_OPTIONS + ' does not contain a valid json definition (actual: ' + this.getAttribute(ATTRIBUTE_OPTIONS) + ').');
+            throw new Error('the options does not contain a valid json definition (actual: ' + data + ').');
         }
     }
 
@@ -455,5 +573,5 @@ function registerCustomElement(element) {
     getGlobalObject('customElements').define(element.getTag(), element);
 }
 
-Monster.assignToNamespace('Monster.DOM', CustomElement, registerCustomElement);
+assignToNamespace('Monster.DOM', CustomElement, registerCustomElement);
 export {Monster, registerCustomElement, CustomElement, initMethodSymbol, assembleMethodSymbol}