@schukai/monster 1.24.0 → 1.25.0

package/source/dom/resource/script.js

@@ -0,0 +1,112 @@
+'use strict';
+
+/**
+ * @author schukai GmbH
+ */
+
+import {extend} from "../../data/extend.js";
+import {assignToNamespace, Monster} from "../../namespace.js";
+import {
+    ATTRIBUTE_CLASS,
+    ATTRIBUTE_ID,
+    ATTRIBUTE_NONCE,
+    ATTRIBUTE_SRC,
+    ATTRIBUTE_TITLE,
+    ATTRIBUTE_TYPE,
+    TAG_SCRIPT
+} from "../constants.js";
+import {KEY_DOCUMENT, referenceSymbol, Resource} from "../resource.js";
+
+
+/**
+ * This class is used by the resource manager to embed scripts.
+ *
+ * You can call the method via the monster namespace `new Monster.DOM.Resource.Script()`.
+ *
+ * ```
+ * <script type="module">
+ * import {Monster} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.25.0/dist/modules/dom/resource/script.js';
+ * new Monster.DOM.Resource.Script()
+ * </script>
+ * ```
+ *
+ * Alternatively, you can also integrate this function individually.
+ *
+ * ```
+ * <script type="module">
+ * import {Script} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.25.0/dist/modules/dom/resource/script.js';
+ * new Script()
+ * </script>
+ * ```
+ *
+ * @since 1.25.0
+ * @copyright schukai GmbH
+ * @memberOf Monster.DOM.Resource
+ * @summary A Resource class
+ */
+class Script extends Resource {
+
+    /**
+     * @property {boolean} async=true {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script#attr-async}
+     * @property {string} crossOrigin=anonymous {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script#attr-crossorigin}
+     * @property {boolean} defer=false {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script#attr-defer}
+     * @property {string} integrity {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script#attr-integrity}
+     * @property {boolean} nomodule {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script#attr-nomodule}
+     * @property {string} nonce {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script#attr-nonce}
+     * @property {string} referrerpolicy {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script#attr-referrerpolicy}
+     * @property {string} type {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script#attr-type}
+     */
+    get defaults() {
+        return extend({}, super.defaults, {
+            async: true,
+            crossOrigin: 'anonymous',
+            defer: false,
+            integrity: undefined,
+            nomodule: false,
+            nonce: undefined,
+            referrerpolicy: undefined,
+            type: 'text/javascript',
+        })
+    }
+
+    /**
+     *
+     * @return {Monster.DOM.Resource.Script}
+     */
+    create() {
+        createElement.call(this);
+        return this;
+    }
+
+    /**
+     * @return {string}
+     */
+    static getURLAttribute() {
+        return ATTRIBUTE_SRC
+    }
+
+}
+
+/**
+ * @private
+ * @return {Monster.DOM.Resource.Script}
+ */
+function createElement() {
+    const self = this;
+
+    const document = self.getOption(KEY_DOCUMENT);
+    self[referenceSymbol] = document.createElement(TAG_SCRIPT);
+
+    for (let key of ['crossOrigin', 'defer', 'async', 'integrity', 'nomodule', ATTRIBUTE_NONCE, 'referrerpolicy', ATTRIBUTE_TYPE, ATTRIBUTE_SRC, ATTRIBUTE_ID, ATTRIBUTE_CLASS, ATTRIBUTE_TITLE]) {
+        if (self.getOption(key) !== undefined) {
+            self[referenceSymbol][key] = self.getOption(key);
+        }
+    }
+
+
+    return self;
+}
+
+
+assignToNamespace('Monster.DOM.Resource', Script);
+export {Monster, Script}

package/source/dom/resource.js

@@ -0,0 +1,268 @@
+'use strict';
+
+/**
+ * @author schukai GmbH
+ */
+
+import {internalStateSymbol, internalSymbol,} from "../constants.js";
+import {extend} from "../data/extend.js";
+import {assignToNamespace, Monster} from "../namespace.js";
+import {BaseWithOptions} from "../types/basewithoptions.js";
+import {getGlobalObject} from "../types/global.js";
+import {ID} from "../types/id.js";
+import {isString} from "../types/is.js";
+import {Observer} from "../types/observer.js";
+import {ProxyObserver} from "../types/proxyobserver.js";
+import {ATTRIBUTE_CLASS, ATTRIBUTE_ID, ATTRIBUTE_TITLE} from "./constants.js";
+
+
+/**
+ * @private
+ * @type {string}
+ */
+export const KEY_DOCUMENT = 'document';
+
+/**
+ * @private
+ * @type {string}
+ */
+export const KEY_QUERY = 'query';
+
+/**
+ * @private
+ * @type {string}
+ */
+export const KEY_TIMEOUT = 'timeout';
+
+/**
+ * @private
+ * @type {symbol}
+ */
+export const referenceSymbol = Symbol('reference');
+
+/**
+ * This class is the base class for all resources to be loaded.
+ *
+ * You can call the method via the monster namespace `new Monster.DOM.Resource()`.
+ *
+ * ```
+ * <script type="module">
+ * import {Monster} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.25.0/dist/modules/dom/resource.js';
+ * new Monster.DOM.Resource()
+ * </script>
+ * ```
+ *
+ * Alternatively, you can also integrate this function individually.
+ *
+ * ```
+ * <script type="module">
+ * import {Resource} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.25.0/dist/modules/dom/resource.js';
+ * new Resource()
+ * </script>
+ * ```
+ *
+ * @since 1.25.0
+ * @copyright schukai GmbH
+ * @memberOf Monster.DOM
+ * @summary A Resource class
+ */
+class Resource extends BaseWithOptions {
+
+    /**
+     *
+     * @param {Object|undefined} options
+     */
+    constructor(options) {
+        super(options);
+
+        let uri = this.getOption(this.constructor.getURLAttribute());
+
+        if (uri === undefined) {
+            throw new Error('missing source')
+        } else if (uri instanceof URL) {
+            uri = uri.toString();
+        } else if (!isString(uri)) {
+            throw new Error('unsupported url type')
+        }
+
+        this[internalSymbol][this.constructor.getURLAttribute()] = uri;
+        this[internalStateSymbol] = new ProxyObserver({
+            loaded: false,
+            error: undefined,
+        })
+
+        this[referenceSymbol] = undefined;
+
+    }
+
+    /**
+     * @return {boolean}
+     */
+    isConnected() {
+
+        if (this[referenceSymbol] instanceof HTMLElement) {
+            return this[referenceSymbol].isConnected;
+        }
+
+        return false;
+    }
+
+    /**
+     * This method is overridden by the special classes and creates the DOM object.
+     * This method is also called implicitly, if not yet done explicitly, by calling `connect()`.
+     *
+     * @throws {Error} this method must be implemented by derived classes
+     * @return {Monster.DOM.Resource}
+     */
+    create() {
+        throw new Error("this method must be implemented by derived classes");
+    }
+
+    /**
+     * This method appends the HTMLElement to the specified document.
+     * If the element has not yet been created, `create()` is called implicitly.
+     *
+     * throws {Error} target not found
+     * @return {Monster.DOM.Resource}
+     */
+    connect() {
+
+        if (!(this[referenceSymbol] instanceof HTMLElement)) {
+            this.create();
+        }
+
+        appendToDocument.call(this);
+        return this;
+    }
+
+    /**
+     * @property {Document} document the document object into which the node is to be appended
+     * @property {string} src/href url to the corresponding resource
+     * @property {string} query defines the location where the resource is to be hooked into the dom.
+     * @property {string} id element attribute id
+     * @property {string} title element attribute title
+     * @property {string} class element attribute class
+     * @property {int} timeout timeout
+     */
+    get defaults() {
+        return extend({}, super.defaults, {
+            [this.constructor.getURLAttribute()]: undefined,
+            [KEY_DOCUMENT]: getGlobalObject('document'),
+            [KEY_QUERY]: 'head',
+            [KEY_TIMEOUT]: 10000,
+            [ATTRIBUTE_ID]: (new ID('resource')).toString(),
+            [ATTRIBUTE_CLASS]: undefined,
+            [ATTRIBUTE_TITLE]: undefined
+        })
+    }
+
+    /**
+     * With `available()` you can check if a resource is available.
+     * This is the case when the tag is included and the resource is loaded.
+     *
+     * @return {Promise}
+     */
+    available() {
+        const self = this;
+        if (!(self[referenceSymbol] instanceof HTMLElement)) {
+            return Promise.reject('no element')
+        }
+
+        if (!self.isConnected()) {
+            return Promise.reject('element not connected')
+        }
+
+        if (self[internalStateSymbol].getSubject()['loaded'] === true) {
+
+            if (self[internalStateSymbol].getSubject()['error'] !== undefined) {
+                return Promise.reject(self[internalStateSymbol].getSubject()['error']);
+            }
+
+            return Promise.resolve();
+
+        }
+
+        return new Promise(function (resolve, reject) {
+
+            const timeout = setTimeout(() => {
+                reject('timeout');
+            }, self.getOption('timeout'))
+
+            const observer = new Observer(() => {
+                clearTimeout(timeout);
+                self[internalStateSymbol].detachObserver(observer);
+                resolve();
+            })
+
+            self[internalStateSymbol].attachObserver(observer);
+
+        });
+
+    };
+
+    /**
+     * @return {string}
+     */
+    static getURLAttribute() {
+        throw new Error("this method must be implemented by derived classes");
+    }
+
+}
+
+
+/**
+ * @private
+ * @return {Promise}
+ * throws {Error} target not found
+ */
+function appendToDocument() {
+    const self = this;
+
+    const targetNode = document.querySelector(self.getOption(KEY_QUERY, 'head'))
+    if (!(targetNode instanceof HTMLElement)) {
+        throw new Error('target not found')
+    }
+
+    addEvents.call(self);
+    targetNode.appendChild(self[referenceSymbol]);
+
+    return self;
+}
+
+/**
+ * @private
+ * @return {addEvents}
+ */
+function addEvents() {
+    const self = this;
+
+    const onError = () => {
+
+        self[referenceSymbol].removeEventListener('error', onError);
+        self[referenceSymbol].removeEventListener('load', onLoad);
+
+        self[internalStateSymbol].setSubject({
+            loaded: true,
+            error: self[referenceSymbol][self.constructor.getURLAttribute()] + ' is not available',
+        })
+
+        return;
+    }
+
+    const onLoad = () => {
+        self[referenceSymbol].removeEventListener('error', onError);
+        self[referenceSymbol].removeEventListener('load', onLoad);
+        self[internalStateSymbol].getSubject()['loaded'] = true;
+        return;
+    }
+
+    self[referenceSymbol].addEventListener('load', onLoad, false);
+    self[referenceSymbol].addEventListener('error', onError, false);
+
+    return self;
+
+}
+
+
+assignToNamespace('Monster.DOM', Resource);
+export {Monster, Resource}

package/source/dom/resourcemanager.js

@@ -0,0 +1,214 @@
+'use strict';
+
+/**
+ * @author schukai GmbH
+ */
+
+import {extend} from "../data/extend.js";
+import {assignToNamespace, Monster} from "../namespace.js";
+import {BaseWithOptions} from "../types/basewithoptions.js";
+import {getGlobalObject} from "../types/global.js";
+import {isArray} from "../types/is.js";
+import {ATTRIBUTE_HREF, ATTRIBUTE_SRC} from "./constants.js";
+import {Resource} from "./resource.js";
+import {Data} from "./resource/data.js";
+import {Stylesheet} from "./resource/link/stylesheet.js";
+import {Script} from "./resource/script.js";
+
+
+/**
+ * You can call the method via the monster namespace `new Monster.DOM.ResourceManager()`.
+ *
+ * ```
+ * <script type="module">
+ * import {Monster} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.25.0/dist/modules/dom/resourcemanager.js';
+ * new Monster.DOM.ResourceManager()
+ * </script>
+ * ```
+ *
+ * Alternatively, you can also integrate this function individually.
+ *
+ * ```
+ * <script type="module">
+ * import {Resource} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.25.0/dist/modules/dom/resourcemanager.js';
+ * new ResourceManager()
+ * </script>
+ * ```
+ *
+ * @since 1.25.0
+ * @copyright schukai GmbH
+ * @memberOf Monster.DOM
+ * @summary A Resource class
+ */
+class ResourceManager extends BaseWithOptions {
+
+    /**
+     *
+     * @param {Object} options
+     * throw {Error} unsupported document type
+     */
+    constructor(options) {
+        super(options);
+
+        if (!(this.getOption('document') instanceof Document)) {
+            throw new Error('unsupported document type')
+        }
+
+
+    }
+
+    /**
+     * @property {string} baseurl
+     */
+    getBaseURL() {
+        this.getOption('document')?.baseURL;
+    }
+
+    /**
+     *
+     * @property {HTMLDocument} document=document Document
+     * @property {Object} resources
+     * @property {Array} resources.scripts=[] array with {@link Monster.DOM.Resource.Script} objects
+     * @property {Array} resources.stylesheets=[] array with {@link Monster.DOM.Resource.Link.Stylesheet} objects
+     * @property {Array} resources.data=[] array with {@link Monster.DOM.Resource.Data} objects
+     */
+    get defaults() {
+        return Object.assign({}, super.defaults, {
+            document: getGlobalObject('document'),
+            resources: {
+                scripts: [],
+                stylesheets: [],
+                data: []
+            }
+        })
+    }
+
+    /**
+     * Append Tags to DOM
+     *
+     * @return {Monster.DOM.ResourceManager}
+     * @throws {Error} unsupported resource definition
+     */
+    connect() {
+        runResourceMethod.call(this, 'connect');
+        return this;
+    }
+
+    /**
+     * Check if available
+     *
+     * @return {Promise}
+     * @throws {Error} unsupported resource definition
+     */
+    available() {
+        return Promise.all(runResourceMethod.call(this, 'available'));
+    }
+
+    /**
+     * Add a script
+     *
+     * @param {string|URL} url
+     * @param [Object|undefined} options
+     * @return {Monster.DOM.ResourceManager}
+     * @see Monster.DOM.Resource.Script
+     */
+    addScript(url, options) {
+        return addResource.call(this, 'scripts', url, options);
+    }
+
+
+    /**
+     * Add Stylesheet
+     *
+     * @param {string|URL} url
+     * @param [Object|undefined} options
+     * @return {Monster.DOM.ResourceManager}
+     * @see Monster.DOM.Resource.Link.Stylesheet
+     */
+    addStylesheet(url, options) {
+        return addResource.call(this, 'stylesheets', url, options);
+    }
+
+    /**
+     * Add Data Tag
+     *
+     * @param {string|URL} url
+     * @param [Object|undefined} options
+     * @return {Monster.DOM.ResourceManager}
+     * @see Monster.DOM.Resource.Data
+     */
+    addData(url, options) {
+        return addResource.call(this, 'data', url, options);
+    }
+
+
+}
+
+/**
+ * @private
+ * @param {string} method
+ * @return {Array}
+ */
+function runResourceMethod(method) {
+    const self = this;
+
+    const result = [];
+
+    for (const type of ['scripts', 'stylesheets', 'data']) {
+        const resources = self.getOption('resources.' + type);
+        if (!isArray(resources)) {
+            continue;
+        }
+
+        for (const resource of resources) {
+            if (!(resource instanceof Resource)) {
+                throw new Error('unsupported resource definition')
+            }
+
+            result.push(resource[method]());
+        }
+
+    }
+
+    return result;
+}
+
+/**
+ *
+ * @param {string} type
+ * @param {string|URL} url
+ * @param [Object|undefined} options
+ * @return {Monster.DOM.ResourceManager}
+ * @private
+ */
+function addResource(type, url, options) {
+    const self = this;
+
+    if (url instanceof URL) {
+        url = url.toString();
+    }
+
+    options = options || {}
+
+    let resource;
+    switch (type) {
+        case 'scripts':
+            resource = new Script(extend({}, options, {[ATTRIBUTE_SRC]: url}))
+            break;
+        case 'stylesheets':
+            resource = new Stylesheet(extend({}, options, {[ATTRIBUTE_HREF]: url}))
+            break;
+        case 'data':
+            resource = new Data(extend({}, options, {[ATTRIBUTE_SRC]: url}))
+            break;
+        default:
+            throw new Error('unsupported type ' + type)
+    }
+
+    (self.getOption('resources')?.[type]).push(resource);
+    return self;
+}
+
+
+assignToNamespace('Monster.DOM', ResourceManager);
+export {Monster, ResourceManager}

package/source/dom/template.js

@@ -14,8 +14,8 @@ import {getDocumentTheme} from "./theme.js";
  *
  * ```
  * <script type="module">
- * import {Monster} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.24.0/dist/modules/dom/template.js';
- * console.log(new Monster.DOM.Template())
+ * import {Monster} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.25.0/dist/modules/dom/template.js';
+ * new Monster.DOM.Template()
  * </script>
  * ```
  *
@@ -23,8 +23,8 @@ import {getDocumentTheme} from "./theme.js";
  *
  * ```
  * <script type="module">
- * import {Template} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.24.0/dist/modules/dom/template.js';
- * console.log(new Template())
+ * import {Template} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.25.0/dist/modules/dom/template.js';
+ * new Template()
  * </script>
  * ```
  *
@@ -70,7 +70,7 @@ class Template extends Base {
 /**
  * This method loads a template with the given ID and returns it.
  *
- * To do this, it first fetches the theme of the document and looks for the `data-monster-theme-name` attribute in the HTML tag.
+ * To do this, it first reads the theme of the document and looks for the `data-monster-theme-name` attribute in the HTML tag.
  *
  * ```
  * <html data-monster-theme-name="my-theme">
@@ -80,13 +80,13 @@ class Template extends Base {
  *
  * Now it is looked if there is a template with the given ID and theme `id-theme` and if yes it is returned. 
  * If there is no template a search for a template with the given ID `id` is done. If this is also not found, an error is thrown.
- *
+ * 
  * You can call the method via the monster namespace `Monster.DOM.findDocumentTemplate()`.
  *
  * ```
  * <script type="module">
- * import {Monster} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.24.0/dist/modules/dom/template.js';
- * console.log(Monster.DOM.findDocumentTemplate())
+ * import {Monster} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.25.0/dist/modules/dom/template.js';
+ * Monster.DOM.findDocumentTemplate()
  * </script>
  * ```
  *
@@ -94,11 +94,41 @@ class Template extends Base {
  *
  * ```
  * <script type="module">
- * import {findTemplate} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.24.0/dist/modules/dom/template.js';
- * console.log(findDocumentTemplate())
+ * import {findTemplate} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.25.0/dist/modules/dom/template.js';
+ * findDocumentTemplate()
  * </script>
  * ```
  *
+ * @example
+ *
+ * import { findDocumentTemplate } from "https://cdn.jsdelivr.net/npm/@schukai/monster@1.25.0/dist/modules/dom/template.js";
+ *
+ * const template = document.createElement("template");
+ * template.id = "myTemplate";
+ * template.innerHTML = "<p>my default template</p>";
+ * document.body.appendChild(template);
+ *
+ * const themedTemplate = document.createElement("template");
+ * themedTemplate.id = "myTemplate-myTheme";
+ * themedTemplate.innerHTML = "<p>my themed template</p>";
+ * document.body.appendChild(themedTemplate);
+ *
+ * // loads the temple and since no theme is set the default template
+ * const template1 = findDocumentTemplate("myTemplate");
+ * console.log(template1.createDocumentFragment());
+ * // ↦ '<p>my default template</p>'
+ *
+ * // now we set our own theme
+ * document
+ * .querySelector("html")
+ * .setAttribute("data-monster-theme-name", "myTheme");
+ * 
+ * // now we don't get the default template, 
+ * // but the template with the theme in the id
+ * const template2 = findDocumentTemplate("myTemplate");
+ * console.log(template2.createDocumentFragment());
+ * // ↦ '<p>my themed template</p>'
+ *
  * @param {string} id
  * @param {Node} currentNode
  * @return {Monster.DOM.Template}