@webtides/element-js 1.0.0 → 1.1.0

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);

package/docs/features/properties.md

@@ -1,24 +1,23 @@
 ## Attributes/Properties
 
-With attributes and properties you can build out and define the public API of an element. _element-js_ elements can have
-three different types of properties.
+With attributes and properties you can build out and define the public API of an element. _element-js_ elements can have three different types of properties.
 
 ```javascript
 export class MyElement extends BaseElement {
-	_privatePropery = 'I am private (by convention)';
-	publicProperty = 'I am public';
-
-	properties() {
-		return {
-			reactivePublicProperty: 'I am public & reactive'
-		};
-	}
-
-	log() {
-		console.log(this._privatePropery);
-		console.log(this.publicProperty);
-		console.log(this.reactivePublicProperty);
-	}
+    _privatePropery = 'I am private (by convention)';
+    publicProperty = 'I am public';
+
+    properties() {
+        return {
+            reactivePublicProperty: 'I am public & reactive'
+        };
+    }
+
+    log() {
+        console.log(this._privatePropery);
+        console.log(this.publicProperty);
+        console.log(this.reactivePublicProperty);
+    }
 }
 
 defineElement('my-element', MyElement);
@@ -26,31 +25,20 @@ defineElement('my-element', MyElement);
 
 #### Defining properties in JavaScript
 
-Public properties for JavaScript classes where recently added by the JavaScript standard committee. For more information
-see
-the [Class fields documentation on MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes/Class_fields)
-.
+Public properties for JavaScript classes where recently added by the JavaScript standard committee. For more information see the [Class fields documentation on MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes/Class_fields) .
 
-On top of these fields _element-js_ adds another form of properties - reactive properties. By overwriting
-the `properties()` method on your element and returning an object of key/value pairs you can define a list of reactive
-public properties. Behind the scenes _element-js_ will automatically generate getters and setters for each property and
-trigger an update/render for the element when these properties change.
+On top of these fields _element-js_ adds another form of properties - reactive properties. By overwriting the `properties()` method on your element and returning an object of key/value pairs you can define a list of reactive public properties. Behind the scenes _element-js_ will automatically generate getters and setters for each property and trigger an update/render for the element when these properties change.
 
 All types of properties can be accessed via the `this` operator within the element class or the template function.
 
 #### Using attributes/properties in HTML
 
-_element-js_ will merge all attributes with the reactive properties map. Values set via attribute will always take
-precedence over values defined in the properties map. Attributes will still be defined as properties even when they are
-not set in the properties map.
+_element-js_ will merge all attributes with the reactive properties map. Values set via attribute will always take precedence over values defined in the properties map. Attributes will still be defined as properties even when they are not set in the properties map.
 
-HTML only has the concept of attributes and `string` values. _element-js_ will automatically convert attributes to their
-correct types of `string`, `number`, `boolean`, `array` and `object`.
+HTML only has the concept of attributes and `string` values. _element-js_ will automatically convert attributes to their correct types of `string`, `number`, `boolean`, `array` and `object`.
 
-> In JavaScript you will typically use camelCase for declaring properties. HTML attributes however only can be
-> lowercase. _element-js_ will therefore convert dash-case names to camelCase variables and vice versa.
+> In JavaScript you will typically use camelCase for declaring properties. HTML attributes however only can be lowercase. _element-js_ will therefore convert dash-case names to camelCase variables and vice versa.
 
 #### Property options
 
-Reactive properties can be fine-tuned further by providing options via the constructor. See `propertyOptions`
-in [Constructor options](../concepts/classes.md).
+Reactive properties can be fine-tuned further by providing options via the constructor. See `propertyOptions` in [Constructor options](../concepts/classes.md).

package/docs/features/refs.md

@@ -1,47 +1,39 @@
-
 ### Refs
 
-To avoid constant lookups of (child) elements from your elements _element-js_ will collect all elements with
-a `[ref=“id”]` attribute and make them available as an object on the element itself via the special `this.$refs`
-reference.
-_element-js_ also provides referencing a list of Nodes by adding a dangling `[]` to the refs id `[ref=“entries[]”]`.
-Be aware that list references will override singular references with the same name as they are considered to be more
-explicit.
+To avoid constant lookups of (child) elements from your elements _element-js_ will collect all elements with a `[ref=“id”]` attribute and make them available as an object on the element itself via the special `this.$refs` reference. _element-js_ also provides referencing a list of Nodes by adding a dangling `[]` to the refs id `[ref=“entries[]”]`. Be aware that list references will override singular references with the same name as they are considered to be more explicit.
 
 ```html
-
 <places-search>
-	<input type="text" ref="input"/>
-	<places-list ref="list">
-		<list-entry ref="entries[]">A</list-entry>
-		<list-entry ref="entries[]">B</list-entry>
-		<list-entry ref="entries[]">C</list-entry>
-	</places-list>
+    <input type="text" ref="input" />
+    <places-list ref="list">
+        <list-entry ref="entries[]">A</list-entry>
+        <list-entry ref="entries[]">B</list-entry>
+        <list-entry ref="entries[]">C</list-entry>
+    </places-list>
 </places-search>
 ```
 
 ```javascript
-import {BaseElement, defineElement, html} from '@webtides/element-js';
+import { BaseElement, defineElement, html } from '@webtides/element-js';
 
 export class PlacesSearch extends BaseElement {
-	events() {
-		return {
-			input: {
-				blur: (e) => {
-					// fetch places...
-					const places = [];
-					// update singular ref
-					this.$refs.list = places;
-					// do something with a list reference 
-					this.$refs.entries.forEach(entry => console.log(entry.innerText)); // A , B , C
-				}
-			}
-		};
-	}
+    events() {
+        return {
+            input: {
+                blur: (e) => {
+                    // fetch places...
+                    const places = [];
+                    // update singular ref
+                    this.$refs.list = places;
+                    // do something with a list reference
+                    this.$refs.entries.forEach((entry) => console.log(entry.innerText)); // A , B , C
+                }
+            }
+        };
+    }
 }
 
 defineElement('places-search', PlacesSearch);
 ```
 
-> _element-js_ will smartly add and remove all refs on every update/render cycle to ensure that they will always be
-> correct even though you might have changed the child DOM tree during render cycles.
+> _element-js_ will smartly add and remove all refs on every update/render cycle to ensure that they will always be correct even though you might have changed the child DOM tree during render cycles.

package/docs/features/renderless.md

@@ -1,11 +1,8 @@
-
 ### Not Rendering Elements / BaseElement
 
-More often than not you won't actually need to render anything from your element but rather only trigger some changes on
-other elements, fire events or fetch data and distribute it to related elements.
+More often than not you won't actually need to render anything from your element but rather only trigger some changes on other elements, fire events or fetch data and distribute it to related elements.
 
-A good example for this pattern is to use container elements for fetching data and delegating it to child elements that
-only take attributes/properties and simply render them.
+A good example for this pattern is to use container elements for fetching data and delegating it to child elements that only take attributes/properties and simply render them.
 
 ```html
 
@@ -16,54 +13,51 @@ only take attributes/properties and simply render them.
 ```
 
 ```javascript
-import {BaseElement, defineElement} from '@webtides/element-js';
+import { BaseElement, defineElement } from '@webtides/element-js';
 
 export class PlacesSearch extends BaseElement {
-	events() {
-		return {
-			input: {
-				blur: (e) => {
-					// fetch places...
-					const places = ['list of place objects…'];
-					this.$refs.list = places;
-				}
-			}
-		};
-	}
+    events() {
+        return {
+            input: {
+                blur: (e) => {
+                    // fetch places...
+                    const places = ['list of place objects…'];
+                    this.$refs.list = places;
+                }
+            }
+        };
+    }
 }
 
 defineElement('places-search', PlacesSearch);
 ```
 
-Another good use case for renderless elements is when you need to change some classes or styles on child elements. It is
-a bit like `jQuery` but much better because everything is declaratively composed of little elements instead of having a
-big JavaScript file full of little mutations.
+Another good use case for renderless elements is when you need to change some classes or styles on child elements. It is a bit like `jQuery` but much better because everything is declaratively composed of little elements instead of having a big JavaScript file full of little mutations.
 
 ```html
-
 <dropdown-element>
-	<button>Options</button>
-	<ul ref="“list”" class="“”hidden">
-		<li>Profile</li>
-		<li>Settings</li>
-		<li>Sign out</li>
-	</ul>
+    <button>Options</button>
+    <ul ref="“list”" class="“”hidden">
+        <li>Profile</li>
+        <li>Settings</li>
+        <li>Sign out</li>
+    </ul>
 </dropdown-element>
 ```
 
 ```javascript
-import {BaseElement, defineElement} from '@webtides/element-js';
+import { BaseElement, defineElement } from '@webtides/element-js';
 
 class DropdownElement extends BaseElement {
-	events() {
-		return {
-			button: {
-				click: () => {
-					this.$refs.list.classList.remove('hidden');
-				}
-			}
-		};
-	}
+    events() {
+        return {
+            button: {
+                click: () => {
+                    this.$refs.list.classList.remove('hidden');
+                }
+            }
+        };
+    }
 }
 
 defineElement('dropdown-element', DropdownElement);