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

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

@@ -0,0 +1,243 @@
+# Upgrade Guide
+
+Upgrading from `element-js` v0.x to v1.0
+
+---
+
+`element-js` v1.0 is the first major version since it was released in June 2020. The biggest change is a new and custom DOM Parts renderer that allows us to get rid of `lit-html` making it a dependency free library finally.
+
+We only have a couple of breaking changes and a few removed deprecations. The deprecations have been logged to the console for a while now and we hope that most of them should not be there anymore. And the breaking changes should be mostly changed import paths. So it should only be a matter of copy and paste.
+
+---
+
+## Install element-js v1.0
+
+Update `element-js` using npm:
+
+```
+npm install element-js@latest
+```
+
+## Support for IE 11 has been dropped
+
+Prior to v1.0, we tried our best to make sure features we included in `element-js` worked in IE 11 whenever possible. If you need to support IE 11, we recommend continuing to use `element-js` v0.x until you no longer need to support IE.
+
+## Added `afterUpdate` lifecycle hook upon connecting the elements
+
+`element-js` will now also trigger the `afterUpdate` hook right after the `connected` hook. This is to reduce the cases where you had to do the same things in `connected` and `afterUpdate`. You can now remove those duplicate calls from the `connected` hook.
+
+## Change import paths for main exports
+
+> This only applies if you used the vanilla renderer. For the default `lit-html` renderer you do not need to change the import paths.
+
+Change everything that was imported from:
+
+```javascript
+import { TemplateElement, html } from '@webtides/element-js/src/renderer/vanilla';
+```
+
+to:
+
+```javascript
+import { TemplateElement, html } from '@webtides/element-js';
+```
+
+This must be done for the following classes and functions:
+
+-   BaseElement
+-   StyledElement
+-   TemplateElement
+-   Store
+-   html
+-   toString
+-   defineElement
+-   i18n
+
+## Change import paths for directives
+
+If you used any directives you must change their import paths as well.
+
+For the vanilla renderer we previously had them here:
+
+```javascript
+import { unsafeHTML } from '@webtides/element-js/src/renderer/vanilla/util/directives.js';
+```
+
+And for the `lit-html` renderer you had to import the directives from `lit`:
+
+```javascript
+import { unsafeHTML } from 'lit-html/directives/unsafe-html.js';
+```
+
+In both cases you must now change the imports to our new directives:
+
+```javascript
+import { unsafeHTML } from '@webtides/element-js/src/dom-parts/directives';
+```
+
+## Removed childListUpdate option from constructor options
+
+We removed the deprecated `BaseElement` constructor option `childListUpdate`. Please use the "mutationObserverOptions" dictionary instead.
+
+Change:
+
+```javascript
+class MyElement extends BaseElement {
+    constructor() {
+        super({ childListUpdate: true });
+    }
+}
+```
+
+to:
+
+```javascript
+class MyElement extends BaseElement {
+    constructor() {
+        super({ mutationObserverOptions: { childList: true } });
+    }
+}
+```
+
+For more information on how to configure `mutationObserverOptions` see the docs.
+
+## Removed the `hooks` map
+
+We removed the `hooks` map in the `BaseElement`. Using the hooks() map for lifecycle hooks is not possible anymore! Please overwrite the existing lifecycle hook functions. See the docs for more info.
+
+Change:
+
+```javascript
+class MyElement extends BaseElement {
+    hooks() {
+        return {
+            connected: () => {},
+            beforeUpdate: () => {},
+            afterUpdate: () => {}
+        };
+    }
+}
+```
+
+to:
+
+```javascript
+class MyElement extends BaseElement {
+    connected() {}
+    beforeUpdate() {}
+    afterUpdate() {}
+}
+```
+
+## Removed the `computed` map
+
+We removed the `computed` map in the `BaseElement`. Using the computed() map for computed properties is is not possible anymore! Please use regular JS getters and return the computed value. See the docs for more info.
+
+Change:
+
+```javascript
+class MyElement extends BaseElement {
+    firstName = 'John';
+    lastName = 'Doe';
+
+    computed() {
+        return {
+            name: () => `${this.firstName} ${this.lastName}`
+        };
+    }
+}
+```
+
+to:
+
+```javascript
+class MyElement extends BaseElement {
+    firstName = 'John';
+    lastName = 'Doe';
+
+    get name() {
+        return `${this.firstName} ${this.lastName}`;
+    }
+}
+```
+
+## Removed the `i18n` helper function
+
+We removed the `i18n` helper function. It was a very simple and naive implementation for translating strings in templates. We would recommend to use a more sophisticated i18n solution.
+
+If you still need the same functionality, you can simply add the following function to your code and change the imports accordingly:
+
+```javascript
+/**
+ * Retrieves a translated key from a dictionary on the window object
+ * Example: ${i18n('CustomElement.buttonLabel', 'Label')}
+ * @param {string} key - to be translated
+ * @param {string} fallback - to be used if key is not defined
+ * @return {string} - String of the translated key or fallback or original key
+ */
+export function i18n(key, fallback) {
+    try {
+        const translations = window.elementjs.i18n();
+        if (translations[key] === undefined) {
+            throw 'Translation Missing';
+        }
+
+        return translations[key];
+    } catch (err) {
+        if (fallback) return fallback;
+        else return key;
+    }
+}
+```
+
+## Changed default options for the `dispatch` helper function
+
+We changed the default options when using the `dispatch` helper function. `bubbles`, `cancelable` and `composed` will now be `true` by default.
+
+Also, we changed the parameter signature. Instead of expecting the tree boolean values as parameters after the data value, we now expect an `options` object that is in line with the `CustomEventInit` options for the `CustomEvent` class. This is not a breaking change, and we will still evaluate the old parameter list for now. It will finally be removed in v2.0.
+
+We would recommend that you start using the new syntax. Change this:
+
+```javascript
+this.dispatch('custom-event', 'foo', true, true, true);
+```
+
+to (if you wanted every parameter to be `true` before):
+
+```javascript
+this.dispatch('custom-event', 'foo');
+```
+
+or this (if you had different option values):
+
+```javascript
+this.dispatch('custom-event', 'foo', {
+    bubbles: true,
+    cancelable: false,
+    composed: true
+});
+```
+
+## Changed adoptGlobalStyles
+
+We changed adopting global styles to include ALL global styles now. Previously only one inline <style> with the ID of '#globalStyles' would be adopted. For more information see the docs. We think that this is the behaviour that one would actually want.
+
+If you still need it to be the way it was before, please change the `adoptGlobalStyles` option value from:
+
+```javascript
+export class ShadowElement extends TemplateElement {
+    constructor() {
+        super({ adoptGlobalStyles: true });
+    }
+}
+```
+
+to:
+
+```javascript
+export class ShadowElement extends TemplateElement {
+    constructor() {
+        super({ adoptGlobalStyles: '#globalStyles' });
+    }
+}
+```

package/docs/guide/guide.md

@@ -0,0 +1,112 @@
+
+## Guides/Tooling
+
+### Frontend Stack
+
+### Bundling/Publishing
+
+### Design System
+
+### Style Guide / Best Practices
+
+This is an element style guide created and enforced for the purpose of standardizing elements and file structures.
+
+#### 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.
+
+Example:
+
+```
+├── card-element
+│   ├── card-element.css
+│   ├── card-element.js
+│   └── test
+│       ├── card-element.e2e.js
+│       └── card-element.spec.js
+├── card-content
+│   ├── card-content.css
+│   └── card-content.js
+├── card-title
+│   ├── card-title.css
+│   └── card-title.js
+```
+
+#### Naming
+
+##### 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.
+
+##### -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.
+
+DO NOT do this:
+
+```
+company-card
+    company-card-header
+        company-card-title
+    company-card-content
+    company-card-footer
+```
+
+Instead, use -element for elements with a single noun.
+
+```
+card-element
+    card-header
+        card-title
+    card-content
+    card-footer
+```
+
+##### 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:
+
+```
+menu-element
+menu-controller
+```
+
+```
+card-element
+card-header
+card-content
+```
+
+##### Element (JS class)
+
+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 {
+}
+
+customElements.define('button-element', ButtonElement);
+
+export class MenuElement extends BaseElement {
+}
+
+customElements.define('menu-element', MenuElement);
+```
+
+#### Code organization
+
+##### 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.

package/package.json

@@ -1,17 +1,17 @@
 {
 	"name": "@webtides/element-js",
-	"version": "1.0.0-alpha.4",
+	"version": "1.0.0-alpha.5",
 	"module": "index.js",
-	"main": "dist/index.js",
+	"main": "index.js",
 	"type": "module",
 	"files": [
-		"/dist",
+		"/docs",
 		"/src",
 		"index.js"
 	],
 	"exports": {
 		".": {
-			"browser": "./dist/index.js",
+			"browser": "./index.js",
 			"import": "./index.js",
 			"default": "./index.js"
 		},
@@ -35,21 +35,18 @@
 	],
 	"dependencies": {},
 	"devDependencies": {
-		"@babel/eslint-parser": "^7.18.9",
-		"@open-wc/testing": "^3.1.6",
-		"@web/dev-server": "^0.1.30",
-		"@web/test-runner": "^0.14.0",
+		"@babel/eslint-parser": "^7.23.3",
+		"@open-wc/testing": "^4.0.0",
+		"@web/dev-server": "^0.4.1",
+		"@web/test-runner": "^0.14.1",
 		"babel-eslint": "^10.1.0",
-		"babel-plugin-module-resolver": "^5.0.0",
-		"deepmerge": "^4.2.2",
-		"esbuild": "^0.15.5",
-		"eslint": "8.22.0",
-		"eslint-config-prettier": "^7.2.0",
-		"eslint-plugin-import": "^2.26.0",
-		"eslint-plugin-prettier": "^4.2.1",
-		"husky": "^8.0.1",
-		"lint-staged": "^13.0.3",
-		"prettier": "^2.7.1"
+		"eslint": "8.55.0",
+		"eslint-config-prettier": "^9.1.0",
+		"eslint-plugin-import": "^2.29.0",
+		"eslint-plugin-prettier": "^5.0.1",
+		"husky": "^8.0.3",
+		"lint-staged": "^15.1.0",
+		"prettier": "^3.1.0"
 	},
 	"lint-staged": {
 		"*.{js,json}": [
@@ -59,7 +56,6 @@
 	},
 	"scripts": {
 		"lint": "eslint index.js 'src/**/*.js'",
-		"prepare": "esbuild index.js --outfile=dist/index.js --bundle --format=esm --sourcemap --target=chrome79,firefox68,safari12,edge79",
 		"test": "web-test-runner test/**/*.test.{html,js} --node-resolve",
 		"test:coverage": "web-test-runner test/**/*.test.{html,js} --node-resolve --coverage",
 		"test:watch": "web-test-runner test/**/*.test.{html,js} --node-resolve --watch",

package/src/BaseElement.js

@@ -380,7 +380,7 @@ class BaseElement extends HTMLElement {
 			property in this._options['propertyOptions'] &&
 			this._options['propertyOptions'][property]['notify'] === true
 		) {
-			this.dispatch(`${camelToDash(property)}-changed`, newValue, true);
+			this.dispatch(`${camelToDash(property)}-changed`, newValue);
 		}
 	}
 
@@ -453,7 +453,7 @@ class BaseElement extends HTMLElement {
 	 * @param {any | function} valueOrCallback
 	 */
 	requestContext(propertyName, valueOrCallback) {
-		this.dispatch('request-context', { [propertyName]: valueOrCallback }, true, true, true);
+		this.dispatch('request-context', { [propertyName]: valueOrCallback });
 	}
 
 	/**
@@ -619,10 +619,10 @@ class BaseElement extends HTMLElement {
 	/**
 	 * Helper function for dispatching custom events
 	 * @param {string} name
-	 * @param {Object} data
-	 * @param {CustomEventInit} options
-	 * @param {boolean} cancelable - DEPRECATED
-	 * @param {boolean} composed - DEPRECATED
+	 * @param {Object} [data]
+	 * @param {CustomEventInit} [options]
+	 * @param {boolean} [cancelable] - DEPRECATED
+	 * @param {boolean} [composed] - DEPRECATED
 	 */
 	dispatch(name, data, options, cancelable = false, composed = false) {
 		let eventInit = {};

package/src/dom-parts/AttributePart.js

@@ -120,6 +120,7 @@ export class AttributePart extends Part {
 	 */
 	constructor(node, name, initialValue) {
 		super();
+		node.__part = this; // add Part to comment node for debugging in the browser
 		this.name = name;
 		this.initialValue = initialValue;
 		this.processor = processAttributePart(node.nextElementSibling, this.name);

package/src/dom-parts/ChildNodePart.js

@@ -212,6 +212,8 @@ export class ChildNodePart extends Part {
 
 		let serverSideRendered = false;
 		if (startNode) {
+			startNode.__part = this; // add Part to comment node for debugging in the browser
+
 			const placeholder = startNode.data;
 			const childNodes = [startNode];
 			let childNode = startNode.nextSibling;

package/src/dom-parts/NodePart.js

@@ -22,6 +22,7 @@ export class NodePart extends Part {
 			);
 		}
 		super();
+		node.__part = this; // add Part to comment node for debugging in the browser
 		this.node = node.nextElementSibling;
 		const { directiveClass, values } = initialValue;
 		this.directive = new directiveClass(node.nextElementSibling);

package/src/dom-parts/TemplateResult.js

@@ -99,6 +99,8 @@ const getValue = (value) => {
 					return value.map(getValue).join('');
 				case value instanceof TemplateResult:
 					return value.toString();
+				case value.__unsafeHTML:
+					return value.string;
 			}
 			break;
 		case 'function':

package/src/dom-parts/directives.js

@@ -54,12 +54,14 @@ const choose = (value, cases, defaultCase) => {
 };
 
 /**
- * Renders a given string as HTML instead of text
+ * Renders a given string as HTML instead of text or as unescaped string in SSR mode
  * @param {string} string
- * @returns {function(): Node | string}
+ * @returns {(function(): Node) | { __unsafeHTML: true, string: string }}
  */
 const unsafeHTML = (string) => {
-	if (!globalThis.DOMParser) return () => string;
+	if (!globalThis.DOMParser) {
+		return { __unsafeHTML: true, string };
+	}
 	const node = convertStringToHTML(string).firstChild;
 	const importedNode = globalThis.document?.importNode(node, true);
 	return () => importedNode;