@webtides/element-js 1.0.0-alpha.1 → 1.0.0-alpha.10

package/docs/features/events.md

@@ -0,0 +1,155 @@
+### Events
+
+In HTML you have two ways of communicating between elements. To send “information” down the tree we typically use attributes or properties on child elements. It is not advised to hold references to parent elements and communicate back up via public methods or properties. The preferred way of sending “information” up the tree is via DOM events. Do read all about them see [Introduction to events - Learn web development | MDN](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Building_blocks/Events) .
+
+_element-js_ is nothing special or exceptional here. You can and should use DOM events and Custom DOM events like usual. We do however provide some nice APIs to make working with events a lot more streamlined.
+
+#### Events map
+
+By implementing an `events()` method in your elements class you can return an object with a list of events that should be registered on the element or its children, along with event handlers to be triggered once the event gets fired. You can use any of the native events or even custom events.
+
+The outer key value pairs let you specify regular DOM selectors as the key for the element the event listeners should be registered on. In the inner object you can define key value pairs where the key is the event to be listened for on the element and the value is the callback to be triggered once the event fires. For every event you can get the event as variable passed to the callback.
+
+```javascript
+export class MyElement extends BaseElement {
+    events() {
+        return {
+            this: {
+                click: (e) => console.log('click', e),
+                customEvent: (e) => {
+                    console.log('customEvent', e);
+                }
+            },
+            '[data-increment]': {
+                click: () => this.count++
+            }
+        };
+    }
+}
+```
+
+The nice thing about this pattern is that you will only have one place for all the event logic. You don't have to declare event handlers in the template and then call dedicated methods defined in the element. Everything is nice and compact in one place.
+
+_this_ When using arrow functions as callbacks in the `events()` map you can use `this` as usual and it will belong to the element itself.
+
+_context_ When binding element methods directly as callbacks you would typically have to bind the context to the element itself.
+
+```javascript
+export class MyElement extends BaseElement {
+    events() {
+        return {
+            this: {
+                click: (e) => this.doStuff.bind(this)
+            }
+        };
+    }
+}
+```
+
+_element-js_ will do that for you automatically behind the scenes. So can omit the `bind` in most cases.
+
+```javascript
+export class MyElement extends BaseElement {
+    events() {
+        return {
+            this: {
+                click: (e) => this.doStuff
+            }
+        };
+    }
+}
+```
+
+If you need to bind a different context however you can do that of course.
+
+_Special selectors_ Sometimes you will need to listen to more global events rather than on the element itself or its children. We therefore enable you to define the following selectors as event targets:
+
+-   window
+-   document
+-   this
+
+Since most events will automatically bubble up the tree it is also possible to listen for events that are not directly related to your element.
+
+```javascript
+export class MyElement extends BaseElement {
+    events() {
+        return {
+            this: {
+                click: (e) => console.log('click', e)
+            },
+            window: {
+                scroll: (e) => console.log('scroll', e)
+            },
+            document: {
+                visibilitychange: (e) => {
+                    if (document.visibilityState === 'visible') {
+                        backgroundMusic.play();
+                    } else {
+                        backgroundMusic.pause();
+                    }
+                }
+            }
+        };
+    }
+}
+```
+
+For better control Events can be bound with listener options by using the "complex notation" The callback need to wrapped into an Object to pass the Options alongside.
+
+```js
+{
+	listener: (e) => console.log('scroll', e),
+		options
+:
+	{
+		passive : true
+	}
+}
+```
+
+Naming is heavily inspired by the addEventListener signature https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener
+
+```javascript
+export class MyElement extends BaseElement {
+    events() {
+        return {
+            window: {
+                scroll: {
+                    listener: (e) => console.log('scroll', e),
+                    options: { passive: true }
+                }
+            }
+        };
+    }
+}
+```
+
+> _element-js_ will smartly add and remove all the defined event listeners on every update/render cycle to ensure that events will always fire even though you might have changed the child DOM tree during render cycles.
+
+#### Dispatching events
+
+To make it easy to dispatch events from your elements itself _element-js_ implements a special method `dispatch()` .
+
+```javascript
+export class BaseElement {
+    dispatch(name, data, options = { bubbles: true, cancelable: true, composed: true }) {
+        const event = new CustomEvent(name, {
+            bubbles: options.bubbles,
+            cancelable: options.cancelable,
+            composed: options.composed,
+            detail: data
+        });
+        this.dispatchEvent(event);
+    }
+}
+```
+
+You can of course still always build them yourself like above, but it is much easier and faster to use like this:
+
+```javascript
+export class MyElement extends BaseElement {
+    someMethod() {
+        this.dispatch('customEvent', { key: 'value' });
+    }
+}
+```

package/docs/features/global-styles.md

@@ -0,0 +1,131 @@
+#### Global Styles / CSS
+
+More often than not you will be building elements for a specific design/layout rather than encapsulated and abstract elements. It is therefore common to style things globally - especially since the rise of utility based CSS frameworks. When elements render in shadow DOM - they will be encapsulated and won't get any styles applied to them like the rest of the document.
+
+There is no official and preferred way of sharing styles between documents today. _element-js_ therefore has a custom solution to this problem. The `TemplateElement` from _element-js_ has another constructor option named: `adoptGlobalStyles` which is `true` by default. When set to `true` _element-js_ will look for all styles (<style></style> and <link rel="stylesheet" />) in the document (head and body) and apply them before any custom/element styles inside the shadow DOM.
+
+> Under the hood _element-js_ will copy/clone the global styles and cache them efficiently as `CSSStyleSheets` so that they can be adopted by multiple shadow DOM elements.
+
+Example:
+
+```html
+<html>
+    <head>
+        <style id="globalStylesId">
+            .red {
+                color: red;
+            }
+        </style>
+        <link class="globalStylesClass" rel="stylesheet" href="blue-styles.css" />
+    </head>
+    <body>
+        <style>
+            .green {
+                color: green;
+            }
+        </style>
+        <link rel="stylesheet" href="yellow-styles.css" />
+    </body>
+</html>
+```
+
+```javascript
+export class ShadowElement extends TemplateElement {
+    constructor() {
+        super({ shadowRender: true, adoptGlobalStyles: true });
+    }
+
+    template() {
+        return html`
+            <p class="red">
+                I will be red although I am in shadow DOM and my element did not provide any CSS itself :)
+            </p>
+            <p class="green">
+                I will be green although I am in shadow DOM and my element did not provide any CSS itself :)
+            </p>
+            <p class="blue">
+                I will be blue although I am in shadow DOM and my element did not provide any CSS itself :)
+            </p>
+            <p class="yellow">
+                I will be yellow although I am in shadow DOM and my element did not provide any CSS itself :)
+            </p>
+        `;
+    }
+}
+```
+
+Instead of adopting all global styles it is also possible to only apply a selection of styles from the global document.
+
+```javascript
+export class ShadowElement extends TemplateElement {
+    constructor() {
+        super({ shadowRender: true, adoptGlobalStyles: '#globalStylesId' });
+    }
+
+    template() {
+        return html`
+            <p class="red">
+                I will be red although I am in shadow DOM and my element did not provide any CSS itself :)
+            </p>
+        `;
+    }
+}
+```
+
+or
+
+```javascript
+export class ShadowElement extends TemplateElement {
+    constructor() {
+        super({ shadowRender: true, adoptGlobalStyles: ['#globalStylesId', '.globalStylesClass'] });
+    }
+
+    template() {
+        return html`
+            <p class="red">
+                I will be red although I am in shadow DOM and my element did not provide any CSS itself :)
+            </p>
+            <p class="blue">
+                I will be blue although I am in shadow DOM and my element did not provide any CSS itself :)
+            </p>
+        `;
+    }
+}
+```
+
+There is one special case for adopted styles in the document. Not only can shadow roots have `.adoptedStyleSheets`, but also the `document`. In case there would be global styles added there you can adopt them by using the special `document` selector.
+
+```javascript
+const globalStyle = new CSSStyleSheet();
+globalStyle.replaceSync(`.red { color: red;}`);
+document.adoptedStyleSheets.push(globalStyle);
+
+export class ShadowElement extends TemplateElement {
+    constructor() {
+        super({ shadowRender: true, adoptGlobalStyles: 'document' });
+    }
+
+    template() {
+        return html`
+            <p class="red">
+                I will be red although I am in shadow DOM and my element did not provide any CSS itself :)
+            </p>
+        `;
+    }
+}
+```
+
+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. 
+
+To enable global style observation you can add the following (inline, sync) script block to yor HTML.
+
+```html
+<script>
+    /** @type {ElementJsConfig} */
+    globalThis.elementJsConfig = {
+        observeGlobalStyles: true
+    };
+</script>
+```

package/docs/features/methods.md

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

package/docs/features/properties.md

@@ -0,0 +1,56 @@
+## 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.
+
+```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);
+	}
+}
+
+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)
+.
+
+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.
+
+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.
+
+#### Property options
+
+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

@@ -0,0 +1,47 @@
+
+### 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.
+
+```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>
+</places-search>
+```
+
+```javascript
+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
+				}
+			}
+		};
+	}
+}
+
+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.

package/docs/features/renderless.md

@@ -0,0 +1,70 @@
+
+### 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.
+
+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
+
+<places-search>
+	<input type=“text" ref=“input”/>
+	<places-list ref="list”></places-list>
+</places-search>
+```
+
+```javascript
+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;
+				}
+			}
+		};
+	}
+}
+
+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.
+
+```html
+
+<dropdown-element>
+	<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';
+
+class DropdownElement extends BaseElement {
+	events() {
+		return {
+			button: {
+				click: () => {
+					this.$refs.list.classList.remove('hidden');
+				}
+			}
+		};
+	}
+}
+
+defineElement('dropdown-element', DropdownElement);
+```

package/docs/features/store.md

@@ -0,0 +1,143 @@
+#### 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.
+
+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.
+
+##### store.js
+
+```js
+export const simpleStore = new Store({
+	value: 'simple'
+})
+
+class MoreComplexStore extends Store {
+	properties() {
+		return {
+			storeCount: 1
+		};
+	}
+	get sum() {
+		return this.storeCount + this.argumentCount;
+	}
+}
+export const exampleStore = new MoreComplexStore({
+	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
+		};
+	}
+}
+export const mediaStore = new MediaStore()
+
+export const scrollYStore = new Store(0)
+window.addEventListener('scroll', () => {
+	scrollYStore.value = window.scrollY;
+});
+
+
+```
+
+##### MyElement.js
+
+```js 
+
+import { exampleStore, simpleStore, mediaStore } from './store.js'; 
+
+export class MyElement extends TemplateElement {
+    properties() {
+        return {
+            store: simpleStore,
+            exampleStore,
+            mediaStore,
+            scrollYStore
+        };
+    }
+
+    template() {
+        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>Scoll Position: ${this.scrollYStore}</div>
+        	`
+    }
+}
+
+export class AnotherElement extends TemplateElement {
+    properties() {
+        return {
+            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 
+
+class NestedStore extends Store {
+	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
+			},
+		};
+	}
+}
+
+```         
+