@webtides/element-js 1.0.0-alpha.9 → 1.1.0

package/docs/concepts/classes.md

@@ -4,8 +4,7 @@ Most of the _element-js_ API ist standard ES6 class Syntax with a few ES next pr
 
 An _element-js_ element is nothing more than a regular JS class that extends from `HTMLElement`.
 
-> For more information on JavaScript classes
-> see: [Classes on MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes)
+> For more information on JavaScript classes see: [Classes on MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes)
 
 ### Constructor & Options
 
@@ -15,42 +14,36 @@ Optionally you can overwrite the constructor and pass an object to the super cal
 
 ```json
 {
-	"autoUpdate": true,
-	"deferUpdate": false,
-	"mutationObserverOptions": {
-		"attributes": true,
-		"childList": true,
-		"subtree": false
-	},
-	"propertyOptions": {},
-	"shadowRender": false,
-	"styles": []
+    "autoUpdate": true,
+    "deferUpdate": false,
+    "mutationObserverOptions": {
+        "attributes": true,
+        "childList": true,
+        "subtree": false
+    },
+    "propertyOptions": {},
+    "shadowRender": false,
+    "styles": []
 }
 ```
 
-
 #### autoUpdate
 
 Type: `boolean` Default: `true`
 
-When set to `true` the element will call the `requestUpdate()` method on the instance every time a property or attribute
-was changed. This will re-evaluate everything on the element and trigger a re-render (if a template is provided) and
-trigger the watchers for the affected properties/attributes.
+When set to `true` the element will call the `requestUpdate()` method on the instance every time a property or attribute was changed. This will re-evaluate everything on the element and trigger a re-render (if a template is provided) and trigger the watchers for the affected properties/attributes.
 
 #### deferUpdate
 
 Type: `boolean` Default: `false`
 
-When set to `true` the element will not call the `requestUpdate()` method upon connecting and therefore will not
-render (if template was provided) initially. This might be necessary in some cases where you have to prepare and setup
-your element before actually rendering for the first time. You will have to call the `requestUpdate` method manually at
-the right lifecycle hook.
+When set to `true` the element will not call the `requestUpdate()` method upon connecting and therefore will not render (if template was provided) initially. This might be necessary in some cases where you have to prepare and setup your element before actually rendering for the first time. You will have to call the `requestUpdate` method manually at the right lifecycle hook.
 
 #### deferUpdate via attribute
 
 deferUpdate can also be set to true by adding a "defer-update" attribute to the host element.
 
-```html 
+```html
 <deferred-element defer-update></deferred-element>
 ```
 
@@ -58,34 +51,23 @@ deferUpdate can also be set to true by adding a "defer-update" attribute to the
 
 Type: `boolean` Default: `false`
 
-When set to `true` the element will early return from the native `connectedCallback()`.
-Setting this to true will defer the entire initialization of `element-js` feature set. 
-To make the element useful at a later point again `connectedCallback()` must be called at a later point.   
+When set to `true` the element will early return from the native `connectedCallback()`. Setting this to true will defer the entire initialization of `element-js` feature set. To make the element useful at a later point again `connectedCallback()` must be called at a later point.
 
 This is an advanced Setting and should be used with great caution.
 
-
 #### deferConnected via attribute (⚠️)
 
 deferConnected can also be set to true by adding a "defer-connected" attribute to the host element.
 
-```html 
+```html
 <deferred-element defer-connected></deferred-element>
 ```
 
-
-
 #### mutationObserverOptions
 
 Type: `object` Default: `{ "attributes": true, "childList": true, "subtree": false }`
 
-By default, the element will register a _Mutation Observer_, listen for attribute changes and call the `requestUpdate`
-method if `autoUpdate` is enabled. When `childList` is set to `true` the element will also call the `requestUpdate`
-method for childList modifications (eg. Adding or removing child elements).
-The `mutationObserverOptions` takes a dictionary in the exact same form as
-the [MutationObserverInit options](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserverInit).
-By setting the `subtree` option to `true` the element will also call the `requestUpdate` method for attribute changes
-and childList modifications on nested child elements.
+By default, the element will register a _Mutation Observer_, listen for attribute changes and call the `requestUpdate` method if `autoUpdate` is enabled. When `childList` is set to `true` the element will also call the `requestUpdate` method for childList modifications (eg. Adding or removing child elements). The `mutationObserverOptions` takes a dictionary in the exact same form as the [MutationObserverInit options](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserverInit). By setting the `subtree` option to `true` the element will also call the `requestUpdate` method for attribute changes and childList modifications on nested child elements.
 
 > Please note that observing `subtree` mutations might have performance implications and use it only if necessary.
 
@@ -108,9 +90,9 @@ With the `propertyOptions` object you can fine tune the update behaviour for cer
 
 ```json
 {
-	"propertyA": {
-		"reflect": true
-	}
+    "propertyA": {
+        "reflect": true
+    }
 }
 ```
 
@@ -118,50 +100,39 @@ By default all options are `false` for all properties/attributes. Currently the
 
 ```json
 {
-	"reflect": false,
-	"parse": false,
-	"notify": false
+    "reflect": false,
+    "parse": false,
+    "notify": false
 }
 ```
 
-_reflect_ When set to `true` the element will reflect property changes back to attributes if the attribute was not
-present when connecting the element. By default all attributes that are present when connecting the element will be
-reflected anyway.
-
-_parse_ When set to `false` the element will not automatically try to parse the attributes string value to a complex
-type (number, array, object).
+_reflect_ When set to `true` the element will reflect property changes back to attributes if the attribute was not present when connecting the element. By default all attributes that are present when connecting the element will be reflected anyway.
 
-_notify_ When set to `true` the element will dispatch `CustomEvent`s for every property/attribute change. The event name
-will be the property name all lowercase and camel to dashes with a postfix of `-changed`. For example `propertyA` will
-dispatch an event with the name `property-a-changed` . The event `detail` property will be the changed property value.
-The event will `bubble` by default.
+_parse_ When set to `false` the element will not automatically try to parse the attributes string value to a complex type (number, array, object).
 
-_parse_ and _reflect_ can also be provided with a callback function for total control of the parsing and/or reflection
-of the attributes value
+_notify_ When set to `true` the element will dispatch `CustomEvent`s for every property/attribute change. The event name will be the property name all lowercase and camel to dashes with a postfix of `-changed`. For example `propertyA` will dispatch an event with the name `property-a-changed` . The event `detail` property will be the changed property value. The event will `bubble` by default.
 
-```js 
+_parse_ and _reflect_ can also be provided with a callback function for total control of the parsing and/or reflection of the attributes value
 
+```js
 propertyOptions = {
-	parseString: {
-		parse: (value) => value.toString()
-	},
-	reflectCustom: {
-		reflect: () => 'custom',
-	},
-}
+    parseString: {
+        parse: (value) => value.toString()
+    },
+    reflectCustom: {
+        reflect: () => 'custom'
+    }
+};
 ```
 
 #### shadowRender
 
 Type: `boolean` Default: `false`
 
-When set to `true` the element will render the template (if provided) in the _Shadow DOM_ and therefore encapsulate the
-element and styles from the rest of the document. For more information on shadow DOM
-see [Using shadow DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM).
+When set to `true` the element will render the template (if provided) in the _Shadow DOM_ and therefore encapsulate the element and styles from the rest of the document. For more information on shadow DOM see [Using shadow DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM).
 
 #### styles
 
 Type `array` Default: `[]`
 
-Via the `styles` option you can add multiple styles/stylesheets to your element. For more information on styling your
-elements see the [Styles](../features/styles.md) section.
+Via the `styles` option you can add multiple styles/stylesheets to your element. For more information on styling your elements see the [Styles](../features/styles.md) section.

package/docs/concepts/hierarchy.md

@@ -1,4 +1,3 @@
-
 ### Element Hierarchy
 
 Pleas keep in mind that lifecycles _do not_ wait for child elements to be connected or updated/rendered.
@@ -6,11 +5,10 @@ Pleas keep in mind that lifecycles _do not_ wait for child elements to be connec
 In the example below we have a simple hierarchy of elements.
 
 ```html
-
 <a-element>
-	<b-element>
-		<c-element></c-element>
-	</b-element>
+    <b-element>
+        <c-element></c-element>
+    </b-element>
 </a-element>
 ```
 
@@ -27,34 +25,34 @@ This loading/connecting behaviour is compliant with how other (normal) DOM eleme
 In the example we render a clock and update the time every second.
 
 ```javascript
-import {TemplateElement, defineElement, html} from '@webtides/element-js';
+import { TemplateElement, defineElement, html } from '@webtides/element-js';
 
 export class ClockElement extends TemplateElement {
-	timer = null;
-
-	properties() {
-		return {
-			time: Date.now()
-		};
-	}
-
-	connected() {
-		this.timer = window.setInterval(() => {
-			this.time = Date.now();
-		}, 1000);
-	}
-
-	disconnected() {
-		window.clearInterval(this.timer);
-	}
-
-	get formattedTime() {
-		return new Date(this.time).toLocaleTimeString();
-	}
-
-	template() {
-		return html` <span>${this.formattedTime}</span> `;
-	}
+    timer = null;
+
+    properties() {
+        return {
+            time: Date.now()
+        };
+    }
+
+    connected() {
+        this.timer = window.setInterval(() => {
+            this.time = Date.now();
+        }, 1000);
+    }
+
+    disconnected() {
+        window.clearInterval(this.timer);
+    }
+
+    get formattedTime() {
+        return new Date(this.time).toLocaleTimeString();
+    }
+
+    template() {
+        return html` <span>${this.formattedTime}</span> `;
+    }
 }
 
 defineElement('clock-element', ClockElement);

package/docs/concepts/lifecycle.md

@@ -1,45 +1,31 @@
-
 ### Lifecycle
 
-Elements have several lifecycle methods which can be used to hook into different moments. By implementing one of the
-following methods within the class the element will call them in the right order:
+Elements have several lifecycle methods which can be used to hook into different moments. By implementing one of the following methods within the class the element will call them in the right order:
 
 #### connected
 
-Called when the element is connected to the DOM and _element-js_ is done initialising. Usually this hook will only be
-called once for the lifetime of your element.
+Called when the element is connected to the DOM and _element-js_ is done initialising. Usually this hook will only be called once for the lifetime of your element.
 
-> Please note that the `connected` hook however /can/ be called more than once after the first time. It will also be
-> invoked when the element is _attached_ or _moved_ in the DOM or to another DOM.
+> Please note that the `connected` hook however /can/ be called more than once after the first time. It will also be invoked when the element is _attached_ or _moved_ in the DOM or to another DOM.
 
 Use it to initialise the element and set public or "private" properties, query for other DOM elements, etc.
 
 #### beforeUpdate
 
-Called when the element is about to be updated. Whenever a /reactive/ property changed, the element will undergo an
-update/render cycle. In this hook you can prepare any internal state that might be needed before the update or render
-actually happens.
+Called when the element is about to be updated. Whenever a /reactive/ property changed, the element will undergo an update/render cycle. In this hook you can prepare any internal state that might be needed before the update or render actually happens.
 
-> Although the element will update/render after connecting to the DOM, the `beforeUpdate` hook won't be called for the
-> first time. Only on subsequent update cycles.
+> Although the element will update/render after connecting to the DOM, the `beforeUpdate` hook won't be called for the first time. Only on subsequent update cycles.
 
-Property changes in this callback will not be applied in the current frame. They will be queued and processed in the
-next frame.
+Property changes in this callback will not be applied in the current frame. They will be queued and processed in the next frame.
 
 #### afterUpdate
 
-Called after the element was updated/rendered. Implement this hook to perform any tasks that need to be done afterwards
-like setting/toggling classes on child elements or invoking API methods on other elements.
+Called after the element was updated/rendered. Implement this hook to perform any tasks that need to be done afterwards like setting/toggling classes on child elements or invoking API methods on other elements.
 
 #### disconnected
 
-Called just before the element is about to be disconnected/removed from the DOM. Use this hook to clear or remove
-everything that might be heavy on the browser like expensive event listeners etc.
+Called just before the element is about to be disconnected/removed from the DOM. Use this hook to clear or remove everything that might be heavy on the browser like expensive event listeners etc.
 
 _DISCALIMER_
 
-The lifecycle hooks described here are custom methods provided by _element-js_. By default custom elements also have two
-baked in hooks. `connectedCallback()` and `disconnectedCallback()`. We would encourage you to avoid these if possible.
-Internally we use them of course to connect the element and trigger the `connected()` callback afterwards. We use them
-to initialise the elements with all the boilerplate and prepare the API that _element-js_ provides. If you absolutely
-must use one of them please keep in mind to call the original callback on the `super` element.
+The lifecycle hooks described here are custom methods provided by _element-js_. By default custom elements also have two baked in hooks. `connectedCallback()` and `disconnectedCallback()`. We would encourage you to avoid these if possible. Internally we use them of course to connect the element and trigger the `connected()` callback afterwards. We use them to initialise the elements with all the boilerplate and prepare the API that _element-js_ provides. If you absolutely must use one of them please keep in mind to call the original callback on the `super` element.

package/docs/concepts/reactivity.md

@@ -1,8 +1,6 @@
-
 ### Reactivity
 
-_element-js_ elements update asynchronously when attributes or reactive properties are changed. Changes will also be
-batched if multiple updates occur. The update itself will always happen in the following frame.
+_element-js_ elements update asynchronously when attributes or reactive properties are changed. Changes will also be batched if multiple updates occur. The update itself will always happen in the following frame.
 
 An update lifecycle roughly looks like this:
 

package/docs/features/computed-properties.md

@@ -1,28 +1,25 @@
 ## Computed properties
 
-Sometimes it is necessary to compute properties out of multiple other properties. You can simply define a getter on the
-element and return a value.
+Sometimes it is necessary to compute properties out of multiple other properties. You can simply define a getter on the element and return a value.
 
 ```javascript
 export class MyElement extends BaseElement {
-	properties() {
-		return {
-			reactivePublicProperty: 'I am public & reactive'
-		};
-	}
+    properties() {
+        return {
+            reactivePublicProperty: 'I am public & reactive'
+        };
+    }
 
-	get computedProperty() {
-		return this.reactivePublicProperty + ' & computed';
-	}
+    get computedProperty() {
+        return this.reactivePublicProperty + ' & computed';
+    }
 
-	log() {
-		console.log(this.computedProperty);
-	}
+    log() {
+        console.log(this.computedProperty);
+    }
 }
 ```
 
 For every subsequent update/render cycle a computed property will be evaluated again.
 
-> Keep in mind that properties (public or private) that are not declared via the `properties()` map will not trigger an
-> update/render cycle when changed. If you use only non reactive properties to compute a property, it will not be
-> re-evaluated automatically.
+> Keep in mind that properties (public or private) that are not declared via the `properties()` map will not trigger an update/render cycle when changed. If you use only non reactive properties to compute a property, it will not be re-evaluated automatically.

package/docs/features/dependency-injection-context-protocol.md

@@ -3,130 +3,118 @@
 _element-js_ provides a simple way of Dependency Injection following the idea of the Context [Protocol Proposal](https://github.com/webcomponents-cg/community-protocols/blob/main/proposals/context.md).
 
 #### Problem "Prop Drilling"
-         
+
 If Data has to be passed down the DOM Tree to descending Child Elements it is usually done by assigning data to the descendants attributes:
 
 ```js
 export class PropDrilling extends TemplateElement {
-	properties() {
-		return {
-			data: {some: "data", which: "bloats", the: "attributes", in: "DOM"  }
-		};
-	}
-	
-	template() {
-	return html`
-		<!-- child element uses the same exacte data-set as the parent does --> 
-		<child-element redundant-data="${data}">
-			<!-- grand child component uses parts of the parents or even the root elements dataset --> 
-			<grand-child-element in-data="${data.in}"></grand-child-element>
-		</child-element>
-		<!-- child component uses parts of the parents dataset -->
-		<another-child-element some-data="${data.some}" the-data="${data.the}"></another-child-element>
-	`;
-	}
+    properties() {
+        return {
+            data: { some: 'data', which: 'bloats', the: 'attributes', in: 'DOM' }
+        };
+    }
+
+    template() {
+        return html`
+            <!-- child element uses the same exacte data-set as the parent does -->
+            <child-element redundant-data="${data}">
+                <!-- grand child component uses parts of the parents or even the root elements dataset -->
+                <grand-child-element in-data="${data.in}"></grand-child-element>
+            </child-element>
+            <!-- child component uses parts of the parents dataset -->
+            <another-child-element some-data="${data.some}" the-data="${data.the}"></another-child-element>
+        `;
+    }
 }
 ```
 
-While this is possible and totally fine for primitive values it can get confusing very fast with a deep nesting and complex data structures.
-It also bloats up the DOM Tree as redundant data ist being passed to multiple descending Elements being copied along the way. 
+While this is possible and totally fine for primitive values it can get confusing very fast with a deep nesting and complex data structures. It also bloats up the DOM Tree as redundant data ist being passed to multiple descending Elements being copied along the way.
+
+#### Dependency Injection for the rescue
 
-#### Dependency Injection for the rescue 
-                                 
 To address the issues caused by "Prop Drilling" _element-js_ provides a simple Dependency Injection Implementation following the idea of the Context Protocol mentioned above.
 
 ##### Provide via provideProperties()
 
-An Element can control whatever is to be "provided" to requesting Elements by implementing the provideProperties function provided by the `BaseElement`.     
+An Element can control whatever is to be "provided" to requesting Elements by implementing the provideProperties function provided by the `BaseElement`.
 
 ```js
-
 export class AncestorElement extends TemplateElement {
-    
-	properties() {
-		return {
-			data: {some: "data", which: "bloats", the: "attributes", in: "DOM"  },
-		};
-	}
-	provideProperties() {
-		return { 
-			data: this.data,
-			in: this.data.in,
-			static: 'string',
-		};
-	}
+    properties() {
+        return {
+            data: { some: 'data', which: 'bloats', the: 'attributes', in: 'DOM' }
+        };
+    }
+    provideProperties() {
+        return {
+            data: this.data,
+            in: this.data.in,
+            static: 'string'
+        };
+    }
 }
 ```
+
 #### Vanilla JS Provide via Event Listener / Context Protocol
 
 ```html
 <script>
-	document.addEventListener('request-context', (event) => {
-		// global value
-		const vanillaValue = 'vanillaValue';
-		for (const [key, value] of Object.entries(event.detail)) {
-			if(key === 'vanillaContext') {
-				if (typeof value === 'function') {
-					// call function with context value
-					value(vanillaValue);
-				} else {
-					// assign as a property to Requestee 
-					event.target[key] = vanillaValue;
-				}        
-			}
-		}
-	};
+    document.addEventListener('request-context', (event) => {
+    	// global value
+    	const vanillaValue = 'vanillaValue';
+    	for (const [key, value] of Object.entries(event.detail)) {
+    		if(key === 'vanillaContext') {
+    			if (typeof value === 'function') {
+    				// call function with context value
+    				value(vanillaValue);
+    			} else {
+    				// assign as a property to Requestee
+    				event.target[key] = vanillaValue;
+    			}
+    		}
+    	}
+    };
 </script>
 ```
 
-
-
 ##### Inject Properties via injectProperties()
 
-An Element can define injection requests by implementing the injectProperties function provided by the `BaseElement`.
-The initial values will also function as default values and will be replaced after the injection request is fulfilled by an Ancestor that provides a property with the requested name.
-Injected properties will automatically become reactive properties within the elements scope. DEVs do not have to care about where the Value is actually coming from. 
-It will be just there at some Point after the Injection will trigger changes / updates just like regular [properties](./properties.md)..   
+An Element can define injection requests by implementing the injectProperties function provided by the `BaseElement`. The initial values will also function as default values and will be replaced after the injection request is fulfilled by an Ancestor that provides a property with the requested name. Injected properties will automatically become reactive properties within the elements scope. DEVs do not have to care about where the Value is actually coming from. It will be just there at some Point after the Injection will trigger changes / updates just like regular [properties](./properties.md)..
 
 ```js
 export class DescendingElement extends TemplateElement {
-
-	injectProperties() {
-		return {
-			in: '',
-			data: {},
-			static: '',
-			vanillaContext: '',
-		};
-	}
+    injectProperties() {
+        return {
+            in: '',
+            data: {},
+            static: '',
+            vanillaContext: ''
+        };
+    }
 }
-
 ```
 
 ##### Request Context Values via manual context Request
 
-If you want more control over what happens with an injected value after the Injection you can do a manual context Request by using the builtin requestContext function of the BaseElement.   
+If you want more control over what happens with an injected value after the Injection you can do a manual context Request by using the builtin requestContext function of the BaseElement.
+
 ```js
 export class ManualRequestElement extends TemplateElement {
-	properties() {
-		return {
-			reversedArray: [],
-		};
-	}
-	connected() {
-		this.requestContext('regularArray', (injectedArray) => {
-		// do whatever you like with the value
-		const processedArray = injectedArray.reverse();
-		// OPTIONAL assign to a property to trigger an update and render the reversed values´
-		this.reversedArray = processedArray;
-	});
-	}
+    properties() {
+        return {
+            reversedArray: []
+        };
+    }
+    connected() {
+        this.requestContext('regularArray', (injectedArray) => {
+            // do whatever you like with the value
+            const processedArray = injectedArray.reverse();
+            // OPTIONAL assign to a property to trigger an update and render the reversed values´
+            this.reversedArray = processedArray;
+        });
+    }
 }
 ```
 
-Still looking for more Information ?                 
+Still looking for more Information ?  
 You might take a look at the [Test Implementation](../../test/unit/context-protocol.test.html) which should cover all cases
-
-
-                                       
-

package/docs/features/global-styles.md

@@ -117,7 +117,7 @@ export class ShadowElement extends TemplateElement {
 
 By default, _element-js_ will only apply all style elements from the global document that are present in the initial HTML. It will not observe the document for any changes regarding style elements.
 
-> Observing global styles is done via a MutationObserver on the whole document. This might impose performance issues. 
+> Observing global styles is done via a MutationObserver on the whole document. This might impose performance issues.
 
 To enable global style observation you can add the following (inline, sync) script block to yor HTML.
 

package/docs/features/methods.md

@@ -1,33 +1,32 @@
-
 ### Methods
 
 Besides public properties you can also shape the API for your element with public methods.
 
 ```javascript
-import {BaseElement, defineElement} from '@webtides/element-js';
+import { BaseElement, defineElement } from '@webtides/element-js';
 
 export class ModalElement extends BaseElement {
-	open() {
-		// do the things to actually open the modal…
-	}
+    open() {
+        // do the things to actually open the modal…
+    }
 }
 
 defineElement('modal-element', ModalElement);
 ```
 
 ```javascript
-import {BaseElement, defineElement} from '@webtides/element-js';
+import { BaseElement, defineElement } from '@webtides/element-js';
 
 export class OtherElement extends BaseElement {
-	events() {
-		return {
-			this: {
-				click: () => {
-					this.$refs.modal.open();
-				}
-			}
-		};
-	}
+    events() {
+        return {
+            this: {
+                click: () => {
+                    this.$refs.modal.open();
+                }
+            }
+        };
+    }
 }
 
 defineElement('other-element', OtherElement);