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

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

package/docs/features/store.md

@@ -1,14 +1,8 @@
 #### Shared State / Reactive State / Store
 
-When a certain property in the properties map is an instance of the provided class `Store` it is treated as an
-external `Store`.
-A `Store` can be created outside a components´ scope or in a dedicated Module to keep track of shared Application
-State.
-When a components´ property is an instance of a `Store` the instance will be added as an observer and
-automatically updated when the store ist changed.
+When a certain property in the properties map is an instance of the provided class `Store` it is treated as an external `Store`. A `Store` can be created outside a components´ scope or in a dedicated Module to keep track of shared Application State. When a components´ property is an instance of a `Store` the instance will be added as an observer and automatically updated when the store ist changed.
 
-Instances of Store provide a way to share global state between as many components in an application as you like.
-Shared State can be something very simple as (updated) Viewport Dimensions, Media Changes or complex fetched data from a REST Endpoint.
+Instances of Store provide a way to share global state between as many components in an application as you like. Shared State can be something very simple as (updated) Viewport Dimensions, Media Changes or complex fetched data from a REST Endpoint.
 
 Stores can also be initialized with a primitive value (Numbers, Booleans). Such stores will switch to a single Property Mode and provide direct access tio the property value via the stores valueOf / toString Function for direct access.
 
@@ -16,53 +10,49 @@ Stores can also be initialized with a primitive value (Numbers, Booleans). Such
 
 ```js
 export const simpleStore = new Store({
-	value: 'simple'
-})
+    value: 'simple'
+});
 
 class MoreComplexStore extends Store {
-	properties() {
-		return {
-			storeCount: 1
-		};
-	}
-	get sum() {
-		return this.storeCount + this.argumentCount;
-	}
+    properties() {
+        return {
+            storeCount: 1
+        };
+    }
+    get sum() {
+        return this.storeCount + this.argumentCount;
+    }
 }
 export const exampleStore = new MoreComplexStore({
-	argumentCount: 1
-})
-
+    argumentCount: 1
+});
 
 class MediaStore extends Store {
-	constructor() {
-		super();
-		const mql = window.matchMedia('(max-width: 600px)');
-		mql.onchange = (e) => {
-			this.isMobile = e.matches;
-		}
-	}
-	properties() {
-		return {
-			isMobile: true
-		};
-	}
+    constructor() {
+        super();
+        const mql = window.matchMedia('(max-width: 600px)');
+        mql.onchange = (e) => {
+            this.isMobile = e.matches;
+        };
+    }
+    properties() {
+        return {
+            isMobile: true
+        };
+    }
 }
-export const mediaStore = new MediaStore()
+export const mediaStore = new MediaStore();
 
-export const scrollYStore = new Store(0)
+export const scrollYStore = new Store(0);
 window.addEventListener('scroll', () => {
-	scrollYStore.value = window.scrollY;
+    scrollYStore.value = window.scrollY;
 });
-
-
 ```
 
 ##### MyElement.js
 
-```js 
-
-import { exampleStore, simpleStore, mediaStore } from './store.js'; 
+```js
+import { exampleStore, simpleStore, mediaStore } from './store.js';
 
 export class MyElement extends TemplateElement {
     properties() {
@@ -78,66 +68,61 @@ export class MyElement extends TemplateElement {
         return `
         	<div>Simple Store: ${this.store.value} == "simple" </div>
         	<div>Complex Store: ${this.exampleStore.sum} == 2</div>
-        	<div>Media: ${this.mediaStore.isMobile ? "MOBILE" : "DESKTOP"}</div>
+        	<div>Media: ${this.mediaStore.isMobile ? 'MOBILE' : 'DESKTOP'}</div>
         	<div>Scoll Position: ${this.scrollYStore}</div>
-        	`
+        	`;
     }
 }
 
 export class AnotherElement extends TemplateElement {
     properties() {
         return {
-            store: simpleStore,
+            store: simpleStore
         };
     }
 
     template() {
         return `
         	<div>Simple Store: ${this.store.value} == the same as in MyElement's template.</div>
-        	`
+        	`;
     }
 }
-
-```         
-
+```
 
 ##### storeception
 
 Changes too nested stores will trigger updates and watcher in ParentStore and ultimately transfer to all elements referencing the parent
 
-```js 
-
+```js
 class NestedStore extends Store {
-	properties() {
-		return {
-			nestedCount: 0,
-		};
-	}
+    properties() {
+        return {
+            nestedCount: 0
+        };
+    }
 }
 
 class ParentStore extends Store {
-	properties() {
-		return {
-			count: 0,		
-			nestedStore: new NestedStore(),
-		};
-	}
-
-	requestUpdate() {
-		// will be triggered on count OR nestedStore.nestedCount changes
-	}
-
-	watch() {
-		return {
-			count: (newCount, oldCount) => {
-				// will be triggered on count changes
-			},
-			nestedStore: () => {
-				// will be triggered on nestedStore changes
-			},
-		};
-	}
-}
+    properties() {
+        return {
+            count: 0,
+            nestedStore: new NestedStore()
+        };
+    }
 
-```         
+    requestUpdate() {
+        // will be triggered on count OR nestedStore.nestedCount changes
+    }
 
+    watch() {
+        return {
+            count: (newCount, oldCount) => {
+                // will be triggered on count changes
+            },
+            nestedStore: () => {
+                // will be triggered on nestedStore changes
+            }
+        };
+    }
+}
+```

package/docs/features/templates.md

@@ -135,7 +135,9 @@ Returns:
 
 **spreadAttributes(attributes)**
 
-Renders multiple attributes as key="value" pairs from a map of attributes.
+Renders multiple attributes as key="value" pairs from a map of attributes.  
+Be aware that `spreadAttributes` only works with the given values and does not remember prior iterations.
+Therefore, it will only add / remove values that are present in the given map.
 
 Parameters:
 
@@ -152,6 +154,7 @@ const attrs = { id: 'myElement', ariaLabel: 'Description' };
 const attributeString = spreadAttributes(attrs);
 // When invoked, returns: "id='myElement' aria-label='Description'"
 ```
+ 
 
 ##### Writing custom directives
 

package/docs/features/watch.md

@@ -1,54 +1,47 @@
-
 ### Watch Changes
 
-Alongside defining reactive properties in the `properties()` map, you can define a watcher for every property by
-implementing a `watch()` map in the same manner.
+Alongside defining reactive properties in the `properties()` map, you can define a watcher for every property by implementing a `watch()` map in the same manner.
 
 ```javascript
 export class MyElement extends BaseElement {
-	properties() {
-		return {
-			property: 'I am public & reactive'
-		};
-	}
-
-	watch() {
-		return {
-			property: (newValue, oldValue) => {
-				console.log('property changed', {newValue, oldValue});
-			}
-		};
-	}
+    properties() {
+        return {
+            property: 'I am public & reactive'
+        };
+    }
+
+    watch() {
+        return {
+            property: (newValue, oldValue) => {
+                console.log('property changed', { newValue, oldValue });
+            }
+        };
+    }
 }
 ```
 
-Whenever a property is changed (either from within the element or from outside) it will trigger the callback defined in
-the `watch()` map if present. The callback will be invoked with the old value and the new value as parameters.
+Whenever a property is changed (either from within the element or from outside) it will trigger the callback defined in the `watch()` map if present. The callback will be invoked with the old value and the new value as parameters.
 
-_element-js_ compares values by stringifying them rather than by reference and will only trigger update/render cycles if
-the value actually changed.
+_element-js_ compares values by stringifying them rather than by reference and will only trigger update/render cycles if the value actually changed.
 
-> `array` or `object` data will not trigger changes if nested elements/keys are changed. Also methods like `push()`
-> and `shift()` won't work.
+> `array` or `object` data will not trigger changes if nested elements/keys are changed. Also methods like `push()` and `shift()` won't work.
 
-Non-mutable operations like `map()` and `shift()` and the spread operator will however change the value and trigger an
-update cycle.
+Non-mutable operations like `map()` and `shift()` and the spread operator will however change the value and trigger an update cycle.
 
 ```javascript
 export class MyElement extends BaseElement {
-	properties() {
-		return {
-			items: ['one', 'two']
-		};
-	}
-
-	count() {
-		this.items = [...this.items, 'three'];
-	}
+    properties() {
+        return {
+            items: ['one', 'two']
+        };
+    }
+
+    count() {
+        this.items = [...this.items, 'three'];
+    }
 }
 ```
 
 The spread operator works for objects and arrays.
 
-If you want to make sure that an update will be triggered you can always request it manually by calling
-the `requestUpdate()` method.
+If you want to make sure that an update will be triggered you can always request it manually by calling the `requestUpdate()` method.

package/docs/getting-started/upgrade-to-v1.md

@@ -75,6 +75,22 @@ In both cases you must now change the imports to our new directives:
 import { unsafeHTML } from '@webtides/element-js/src/dom-parts/directives';
 ```
 
+### element-js@1.1+
+
+since 1.1 its also possible to import directives directly from the modules index
+
+```javascript
+import {
+    classMap,
+    styleMap,
+    when,
+    choose,
+    unsafeHTML,
+    spreadAttributes,
+    optionalAttribute
+} from '@webtides/element-js';
+```
+
 ## Removed childListUpdate option from constructor options
 
 We removed the deprecated `BaseElement` constructor option `childListUpdate`. Please use the "mutationObserverOptions" dictionary instead.

package/docs/guide/guide.md

@@ -1,4 +1,3 @@
-
 ## Guides/Tooling
 
 ### Frontend Stack
@@ -13,10 +12,9 @@ This is an element style guide created and enforced for the purpose of standardi
 
 #### File structure
 
-- One element per file.
-- One element per directory. Though it may make sense to group similar elements into the same directory, we've found it'
-	s easier to consume and document elements when each one has its own directory.
-- Implementation (.js) and styles (.css) of an element should live in the same directory.
+-   One element per file.
+-   One element per directory. Though it may make sense to group similar elements into the same directory, we've found it' s easier to consume and document elements when each one has its own directory.
+-   Implementation (.js) and styles (.css) of an element should live in the same directory.
 
 Example:
 
@@ -39,16 +37,12 @@ Example:
 
 ##### Name
 
-Elements are not actions, they are conceptually "things". It is better to use nouns, instead of verbs, such us: "
-animation" instead of "animating". "input", "tab", "nav", "menu" are some examples.
+Elements are not actions, they are conceptually "things". It is better to use nouns, instead of verbs, such us: " animation" instead of "animating". "input", "tab", "nav", "menu" are some examples.
 
 ##### -element postfix
 
-The naming has a major role when you are creating a collection of elements intended to be used across different
-projects. Web Components are not scoped because they are globally declared within the page, which means a "unique" name
-is needed to prevent collisions.  
-Additionally, web components are required to contain a "-" dash within the tag name. When using the first section to
-namespace your components - everything will look the same, and it will be hard to distinguish elements.
+The naming has a major role when you are creating a collection of elements intended to be used across different projects. Web Components are not scoped because they are globally declared within the page, which means a "unique" name is needed to prevent collisions.  
+Additionally, web components are required to contain a "-" dash within the tag name. When using the first section to namespace your components - everything will look the same, and it will be hard to distinguish elements.
 
 DO NOT do this:
 
@@ -72,8 +66,7 @@ card-element
 
 ##### Modifiers
 
-When several elements are related and/or coupled, it is a good idea to share the name, and then add different modifiers,
-for example:
+When several elements are related and/or coupled, it is a good idea to share the name, and then add different modifiers, for example:
 
 ```
 menu-element
@@ -91,13 +84,11 @@ card-content
 The name of the ES6 class of the element should reflect the file name, and the html tag name.
 
 ```js
-export class ButtonElement extends BaseElement {
-}
+export class ButtonElement extends BaseElement {}
 
 customElements.define('button-element', ButtonElement);
 
-export class MenuElement extends BaseElement {
-}
+export class MenuElement extends BaseElement {}
 
 customElements.define('menu-element', MenuElement);
 ```
@@ -106,7 +97,4 @@ customElements.define('menu-element', MenuElement);
 
 ##### Newspaper Metaphor from The Robert C. Martin's _Clean Code_
 
-> The source file should be organized like a newspaper article, with the highest level summary at the top, and more and
-> more details further down. Functions called from the top function come directly below it, and so on down to the lowest
-> level, and most detailed functions at the bottom. This is a good way to organize the source code, even though IDE:s make
-> the location of functions less important, since it is so easy to navigate in and out of them.
+> The source file should be organized like a newspaper article, with the highest level summary at the top, and more and more details further down. Functions called from the top function come directly below it, and so on down to the lowest level, and most detailed functions at the bottom. This is a good way to organize the source code, even though IDE:s make the location of functions less important, since it is so easy to navigate in and out of them.