@webtides/element-js 1.0.0-alpha.4 → 1.0.0-alpha.6

package/docs/README.md

@@ -0,0 +1,174 @@
+# element-js
+
+## Introduction
+
+_element-js_ is a collection of base classes for Custom Elements with a beautiful API for building fast and lightweight
+Web Components that work with any framework or without a framework at all - because they are just html and vanilla
+javascript.
+
+_element-js_ aims to combine the best concepts of current and popular frontend frameworks and web-standard into a single
+toolset that will never be outdated because it is just html and javascript.
+
+### Why Custom elements
+
+By using web-standards, developers only need to learn the standard web API once rather than custom framework APIs over
+and over again.
+
+While popular frontend frameworks come and go, web components and custom elements will always be part of the web
+standard API. And since they conform to the standard web API, they work in any major frontend framework.
+
+Custom elements provide a component model for the web and enable developers to define their own elements. With custom
+elements you get a mechanism to associate an ES class with a custom element name which then can be used in HTML
+alongside any other element. Inside the class you can define the public API for the custom element.
+
+### Why element-js
+
+Using Custom Clements directly can be quite cumbersome because the underlying API is very low level. To prevent writing
+a lot of boilerplate _element-js_ provides extra APIs that enable writing components fast with very little code.
+
+On top of that it also brings some nice features like
+
+- async update/render cycle
+- automatic mapping of attributes to properties
+- objects, arrays, numbers and booleans as attributes (instead of just strings)
+- reflecting properties to attributes
+- abstraction for writing templates
+- mechanism for loading styles per element
+- loading global styles into Shadow Dom
+
+And the best thing? There is no magic! No Framework. No compiler. You only need to extend from an _element-js_ element
+instead of the standard `HTMLElement`.
+
+### Browser Support
+
+_element-js_ Elements are natively supported in all modern Browsers including Chrome, Edge, Firefox, and Safari.
+
+| Chrome | Edge   | Firefox | Safari   |
+| ------ | ------ | ------- | -------- |
+| ✓      | ✓      | ✓       | ✓        |
+| v. 60+ | v. 79+ | v. 63+  | v. 10.1+ |
+
+If you need to support older Browsers like IE 11 or Edge 16-18 you will have to load one or two polyfills for Custom
+Elements to work seamlessly. _element-js_ does not bring or load any polyfills on its own. You will have to bundle or
+load them yourself. For more information see [Bundling/Publishing](#bundlingpublishing).
+
+> _element-js_ comes unbundled, unminified and uses a few `Babel` plugins. Browser support can also be limited for any
+> of the `Babel` plugin features, you will probably have to use a build step and run your code through something
+> like `Babel`. For a list of `Babel` plugins that are used, see [ES6 Classes](#es6-classes). For more information on
+> bundling and publishing your elements see [Bundling/Publishing](#bundlingpublishing).
+
+### Getting Started
+
++ #### [Upgrade Guide](./getting-started/upgrade-to-v1.md)
+
+### Element Core Concepts
+
++ #### [ES6 Classes & Options](./concepts/classes.md)
++ #### [Lifecycle](./concepts/lifecycle.md)
++ #### [Reactivity](./concepts/reactivity.md)
++ #### [Hierarchy](./concepts/hierarchy.md)
+
+### Features
+
++ #### [Reactive Attributes/Properties](./features/properties.md)
++ #### [Shared State / Reactive State / Store](./features/store.md)
++ #### [Watch Changes](./features/watch.md)
++ #### [Computed Properties](./features/computed-properties.md)
++ #### [Dependency Injection / Context Protocol](./features/dependency-injection-context-protocol.md)
++ #### [Methods](./features/methods.md)
++ #### [Rendering / TemplateElement](./features/templates.md)
++ #### [Not Rendering Elements / BaseElement](./features/methods.md)
++ #### [Dom References / Refs](./features/refs.md)
++ #### [Component Styles / CSS](./features/styles.md)
++ #### [Global Styles / CSS](./features/global-styles.md)
++ #### [Events](./features/events.md)
+
+### Getting started
+
+`npm install @webtides/element-js`
+
+You can install _element-js_ into an existing project or create a new app from scratch.
+
+### First Element
+
+To define a custom element, create a class that extends _element-js_ and pass the class with a name to
+the `defineElement` helper function.
+
+> By specification, a custom element's name can only have lower case letters and must contain a dash.
+
+Here is an example of what a _element-js_ element looks like:
+
+```js
+import {BaseElement, defineElement} from '@webtides/element-js';
+
+class ExampleElement extends BaseElement {
+	// normal public properties
+	greeting = 'Hello';
+	name = 'John';
+
+	// lifecycle hook
+	connected() {
+		this.greet();
+	}
+
+	// reactive attributes/properties
+	properties() {
+		return {
+			familyName: 'Doe'
+		};
+	}
+
+	// watchers for property changes
+	watch() {
+		return {
+			familyName: (newValue, oldValue) => {
+				console.log('familyName changed', newValue, oldValue);
+			}
+		};
+	}
+
+	// computed property
+	get computedMsg() {
+		return `${this.greeting} ${this.name} ${this.familyName}`;
+	}
+
+	// method
+	greet() {
+		alert('greeting: ' + this.computedMsg);
+	}
+}
+
+defineElement('example-element', ExampleElement);
+```
+
+> You don't need to fully understand everything just now. We'll explain each part in detail later on.
+
+When the JS class is built, this element can be imported and used in HTML just like any other element tag.
+
+```html
+
+<example-element family-name="Smith"></example-element>
+<script type="module" src="./example-element.js">
+```
+
+When rendered in the browser, it will log to the console: `Hello John Smith`
+
+
+
+
+## [Guides/Tooling](./guide/guide.md) 
+
+
+## Testing
+
+### Overview
+
+### Feature tests
+
+### Unit tests
+
+## Recommended Packages
+
+### @webtides/element-library
+
+### @webtides/layouts

package/docs/concepts/classes.md

@@ -0,0 +1,167 @@
+### ES6 classes
+
+Most of the _element-js_ API ist standard ES6 class Syntax with a few ES next proposals.
+
+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)
+
+### Constructor & Options
+
+For the most part you won't probably need a constructor when extending your elements from _element-js_.
+
+Optionally you can overwrite the constructor and pass an object to the super call with various element-level options.
+
+```json
+{
+	"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.
+
+#### 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.
+
+#### deferUpdate via attribute
+
+deferUpdate can also be set to true by adding a "defer-update" attribute to the host element.
+
+```html 
+<deferred-element defer-update></deferred-element>
+```
+
+#### deferConnected (⚠️)
+
+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.   
+
+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 
+<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.
+
+> Please note that observing `subtree` mutations might have performance implications and use it only if necessary.
+
+#### propertyOptions:
+
+```js
+{
+	parseDisabled: {
+		parse: false,
+	},
+	parseString: {
+		parse: (value) => value.toString(),
+	},
+},
+```
+
+Type: `object` Default `{}`
+
+With the `propertyOptions` object you can fine tune the update behaviour for certain properties/attributes.
+
+```json
+{
+	"propertyA": {
+		"reflect": true
+	}
+}
+```
+
+By default all options are `false` for all properties/attributes. Currently the following options are available:
+
+```json
+{
+	"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).
+
+_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_ 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',
+	},
+}
+```
+
+#### 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).
+
+#### 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.

package/docs/concepts/hierarchy.md

@@ -0,0 +1,61 @@
+
+### Element Hierarchy
+
+Pleas keep in mind that lifecycles _do not_ wait for child elements to be connected or updated/rendered.
+
+In the example below we have a simple hierarchy of elements.
+
+```html
+
+<a-element>
+	<b-element>
+		<c-element></c-element>
+	</b-element>
+</a-element>
+```
+
+The full lifecycle would be as follows:
+
+1. a-element -> connected()
+2. b-element -> connected()
+3. c-element -> connected()
+
+This loading/connecting behaviour is compliant with how other (normal) DOM elements are loaded and connected.
+
+#### Example
+
+In the example we render a clock and update the time every second.
+
+```javascript
+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> `;
+	}
+}
+
+defineElement('clock-element', ClockElement);
+```

package/docs/concepts/lifecycle.md

@@ -0,0 +1,45 @@
+
+### 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:
+
+#### 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.
+
+> 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.
+
+> 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.
+
+#### 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.
+
+#### 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.
+
+_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.

package/docs/concepts/reactivity.md

@@ -0,0 +1,14 @@
+
+### 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.
+
+An update lifecycle roughly looks like this:
+
+1. A property is changed
+2. Check whether the value actually changed and if so, request an update
+3. Requested updates are batched in a queue
+4. Perform the update in the next frame
+5. Trigger Watchers for properties if defined
+6. Render the template if defined

package/docs/features/computed-properties.md

@@ -0,0 +1,28 @@
+## 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.
+
+```javascript
+export class MyElement extends BaseElement {
+	properties() {
+		return {
+			reactivePublicProperty: 'I am public & reactive'
+		};
+	}
+
+	get computedProperty() {
+		return this.reactivePublicProperty + ' & computed';
+	}
+
+	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.

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

@@ -0,0 +1,132 @@
+### Dependency Injection
+
+_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>
+	`;
+	}
+}
+```
+
+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 
+                                 
+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`.     
+
+```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',
+		};
+	}
+}
+```
+#### 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;
+				}        
+			}
+		}
+	};
+</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)..   
+
+```js
+export class DescendingElement extends TemplateElement {
+
+	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.   
+```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;
+	});
+	}
+}
+```
+
+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
+
+
+                                       
+