@webtides/element-js 0.7.3 → 1.0.0-alpha.2

package/index.js

@@ -5,5 +5,6 @@ import { toString } from './src/util/toString.js';
 import { defineElement } from './src/util/defineElement.js';
 import { i18n } from './src/util/i18n.js';
 import { Store } from './src/util/Store.js';
+import { Directive } from './src/util/Directive.js';
 
-export { BaseElement, StyledElement, TemplateElement, Store, html, toString, defineElement, i18n };
+export { BaseElement, StyledElement, TemplateElement, Store, Directive, html, toString, defineElement, i18n };

package/package.json

@@ -1,8 +1,9 @@
 {
 	"name": "@webtides/element-js",
-	"version": "0.7.3",
+	"version": "1.0.0-alpha.2",
 	"module": "index.js",
 	"main": "dist/index.js",
+	"type": "module",
 	"files": [
 		"/dist",
 		"/src",
@@ -16,12 +17,7 @@
 		},
 		"./src/*": "./src/*.js",
 		"./src/util/*": "./src/util/*.js",
-		"./src/renderer/vanilla": "./src/renderer/vanilla/index.js",
-		"./src/renderer/vanilla/TemplateElement": "./src/renderer/vanilla/TemplateElement.js",
-		"./src/renderer/vanilla/util/*": "./src/renderer/vanilla/util/*.js",
-		"./src/renderer/vanilla/util/directives.js": "./src/renderer/vanilla/util/directives.js",
-		"./src/renderer/vanilla/util/html.js": "./src/renderer/vanilla/util/html.js",
-		"./src/renderer/vanilla/util/render.js": "./src/renderer/vanilla/util/render.js"
+		"./src/dom-parts/*": "./src/dom-parts/*.js"
 	},
 	"repository": "https://github.com/webtides/element-js.git",
 	"author": "@webtides",
@@ -37,23 +33,23 @@
 		"element-js",
 		"shadow-dom"
 	],
-	"dependencies": {
-		"lit-html": "^1.2.1"
-	},
+	"dependencies": {},
 	"devDependencies": {
-		"@open-wc/testing": "^3.0.3",
+		"@babel/eslint-parser": "^7.18.9",
+		"@open-wc/testing": "^3.1.6",
 		"@web/dev-server": "^0.1.30",
-		"@web/test-runner": "^0.13.26",
+		"@web/test-runner": "^0.14.0",
 		"babel-eslint": "^10.1.0",
 		"babel-plugin-module-resolver": "^5.0.0",
 		"deepmerge": "^4.2.2",
-		"esbuild": "^0.8.57",
-		"eslint": "^7.0.0",
-		"eslint-config-prettier": "^6.11.0",
-		"eslint-plugin-prettier": "^3.1.3",
-		"husky": "^7.0.4",
-		"lint-staged": "^12.1.2",
-		"prettier": "^2.5.1"
+		"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"
 	},
 	"lint-staged": {
 		"*.{js,json}": [
@@ -62,7 +58,7 @@
 		]
 	},
 	"scripts": {
-		"lint": "eslint src/**/*.js",
+		"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",

package/src/BaseElement.js

@@ -5,7 +5,44 @@ import { Store } from './util/Store.js';
 export { defineElement } from './util/defineElement.js';
 export { toString } from './util/toString.js';
 
+/**
+ * Options object for the BaseElement
+ * @typedef {Object} BaseElementOptions
+ * @property {boolean} [autoUpdate] - 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. Default is `true`
+ * @property {boolean} [deferUpdate] - When set to true the element will not call the requestUpdate() method upon connecting and therefore will not render (if template was provided) initially. Default is `true`
+ * @property {MutationObserverOptions} [mutationObserverOptions]
+ * @property {PropertyOptions} [propertyOptions]
+ */
+
+/**
+ * Options object for the BaseElement mutationObserverOptions option
+ * @typedef {Object} MutationObserverOptions
+ * @property {boolean} [childList] - When childList is set to true the element will also call the requestUpdate method for childList modifications (eg. Adding or removing child elements). Default is `true`
+ * @property {boolean} [subtree] - Please note that observing subtree mutations might have performance implications and use it only if necessary. Default is `false`
+ */
+
+/**
+ * Options object for the BaseElement propertyOptions option
+ * @typedef {Object} PropertyOptions
+ * @property {undefined | boolean | function} [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. Default is `undefined`
+ * @property {undefined | boolean | function} [parse] - When set to false the element will not automatically try to parse the attributes string value to a complex type (number, array, object). Default is `undefined`
+ * @property {undefined | boolean | function} [notify] - When set to true the element will dispatch CustomEvents for every property/attribute change. The event name will be the property name all lowercase and camel to dashes with a postfix of -changed. Default is `undefined`
+ */
+
+/**
+ * Options object for updating properties
+ * @typedef {Object} PropertyUpdateOptions
+ * @property {boolean} [notify] - Whether the update should trigger the lifecycle methods. The default is `true`
+ * @property {string} property - The property name
+ * @property {any} newValue - The new value for the property
+ * @property {string} newValueString - The new value as `string` for the property (for comparison reasons)
+ * @property {any} oldValue - The old value for the property
+ */
+
 class BaseElement extends HTMLElement {
+	/**
+	 * @param {BaseElementOptions} options
+	 */
 	constructor(options = {}) {
 		super();
 		this.$refs = {};
@@ -26,15 +63,13 @@ class BaseElement extends HTMLElement {
 			propertyOptions: {},
 			...options,
 		};
-
-		if (options.childListUpdate !== undefined && options.childListUpdate !== null) {
-			this._options.mutationObserverOptions.childList = options.childListUpdate;
-			console.warn(
-				`[${this.localName}] Using the "childListUpdate" option is deprecated and will be removed before 1.0! Please use the "mutationObserverOptions" dictionary instead. See the docs for more info`,
-			);
-		}
 	}
 
+	/**
+	 * Overrides the native `connectedCallback` of the HTMLElement to set up and initialize our element.
+	 * This will define the attributes and properties as reactive getters and setter,
+	 * register observers, refs and events.
+	 */
 	connectedCallback() {
 		// define all attributes to "this" as properties
 		this.defineAttributesAsProperties();
@@ -42,9 +77,6 @@ class BaseElement extends HTMLElement {
 		// define all properties to "this"
 		this.defineProperties();
 
-		// define all computed properties to "this"
-		this.defineComputedProperties();
-
 		// define context
 		this.definePropertyInjection();
 
@@ -52,17 +84,21 @@ class BaseElement extends HTMLElement {
 		this.defineObserver();
 
 		if (this.hasAttribute('defer-update') || this._options.deferUpdate) {
-			// don't updates/render, but register refs and events
+			// don't update/render, but register refs and events
 			this.registerEventsAndRefs();
 
 			this.triggerHook('connected');
 		} else {
 			this.requestUpdate({ notify: false }).then(() => {
 				this.triggerHook('connected');
+				this.triggerHook('afterUpdate');
 			});
 		}
 	}
 
+	/**
+	 * Define a MutationObserver on the element to get notified on attribute changes and childList updates according to the options specified via the constructor options.
+	 */
 	defineObserver() {
 		// see: https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver#Example_usage
 		this._mutationObserver = new MutationObserver((mutations) => {
@@ -95,6 +131,9 @@ class BaseElement extends HTMLElement {
 		});
 	}
 
+	/**
+	 * Native `disconnectedCallback` of the HTMLElement
+	 */
 	disconnectedCallback() {
 		// remove events for elements in the component
 		this.removeEvents();
@@ -116,6 +155,11 @@ class BaseElement extends HTMLElement {
 		this.triggerHook('disconnected');
 	}
 
+	/**
+	 * Request and batch an asynchronous update cycle
+	 * @param {PropertyUpdateOptions} options
+	 * @returns {Promise<unknown>}
+	 */
 	requestUpdate(options = { notify: true }) {
 		if (options.notify === true) {
 			this.triggerHook('beforeUpdate');
@@ -145,6 +189,7 @@ class BaseElement extends HTMLElement {
 	 * This should be called by the template component AFTER adding the template to
 	 * the DOM.
 	 * Here we will register the events and the refs for the element.
+	 * @param {PropertyUpdateOptions} options
 	 */
 	update(options = { notify: true }) {
 		this.registerEventsAndRefs();
@@ -211,6 +256,9 @@ class BaseElement extends HTMLElement {
 	 * Define a property on the element
 	 * Will trigger watch() function when a property was changed
 	 * Will trigger update() when a property was changed
+	 * @param {string} property
+	 * @param {any} value
+	 * @param {boolean} reflectAttribute
 	 */
 	defineProperty(property, value, reflectAttribute = false) {
 		if (value instanceof Store) {
@@ -274,12 +322,10 @@ class BaseElement extends HTMLElement {
 	}
 
 	/**
-	 * call the watch callbacks on property changes
-	 *
-	 * @param context is the elements instance
-	 * @param property property that changes
-	 * @param newValue
-	 * @param oldValue
+	 * Call the watch callbacks on property changes
+	 * @param {string} property property that changes
+	 * @param {any} newValue
+	 * @param {any} oldValue
 	 */
 	callPropertyWatcher(property, newValue, oldValue) {
 		// notify watched properties (after update())
@@ -288,12 +334,11 @@ class BaseElement extends HTMLElement {
 			watch[property](newValue, oldValue);
 		}
 	}
+
 	/**
-	 * notify property observer via change event
-	 *
-	 * @param context is the elements instance
-	 * @param property property that changes
-	 * @param newValue
+	 * Notify property observer via change event
+	 * @param {string} property property that changes
+	 * @param {any} newValue
 	 */
 	notifyPropertyChange(property, newValue) {
 		// dispatch change event
@@ -305,6 +350,10 @@ class BaseElement extends HTMLElement {
 		}
 	}
 
+	/**
+	 * Reflects a property as attribute on the element
+	 * @param {PropertyUpdateOptions} options
+	 */
 	reflectProperty(options) {
 		const { property, newValue } = options;
 		const newValueString = options.newValueString || JSON.stringify(newValue);
@@ -353,9 +402,8 @@ class BaseElement extends HTMLElement {
 
 	/**
 	 * Helper Function to initialize the context requests
-	 *
-	 * @param propertyName
-	 * @param valueOrCallback
+	 * @param {string} propertyName
+	 * @param {any | function} valueOrCallback
 	 */
 	requestContext(propertyName, valueOrCallback) {
 		this.dispatch('request-context', { [propertyName]: valueOrCallback }, true);
@@ -365,8 +413,7 @@ class BaseElement extends HTMLElement {
 	 * Internal Context Request Handler
 	 * This will check if the current/receiving instance actually provides a value under the requested name.
 	 * If there is something to provide it will either assign the value to the requesting element or call the callback.
-	 *
-	 * @param event
+	 * @param {CustomEvent} event
 	 */
 	onRequestContext(event) {
 		const properties = this.properties();
@@ -388,33 +435,31 @@ class BaseElement extends HTMLElement {
 		});
 	}
 
-	// Deprecated
-	hooks() {
-		return {};
-	}
-
-	// Connected lifecycle hook
+	/**
+	 * Connected lifecycle hook
+	 */
 	connected() {}
 
-	// BeforeUpdate lifecycle hook
+	/**
+	 * BeforeUpdate lifecycle hook
+	 */
 	beforeUpdate() {}
 
-	// AfterUpdate lifecycle hook
+	/**
+	 * AfterUpdate lifecycle hook
+	 */
 	afterUpdate() {}
 
-	// Disconnected lifecycle hook
+	/**
+	 * Disconnected lifecycle hook
+	 */
 	disconnected() {}
 
-	// Triggers a lifecycle hook based on the name
+	/**
+	 * Triggers a lifecycle hook based on the name
+	 * @param {string} name
+	 */
 	triggerHook(name) {
-		if (this.hooks && name in this.hooks()) {
-			console.warn(
-				`[${this.localName}] Using the hooks() map for lifecycle hooks is deprecated! Please overwrite the existing lifecycle hook functions. See the docs for more info`,
-			);
-			this.hooks()[name]();
-			return;
-		}
-
 		if (name in this) {
 			this[name]();
 		}
@@ -431,25 +476,6 @@ class BaseElement extends HTMLElement {
 		return {};
 	}
 
-	// Deprecated
-	computed() {
-		return {};
-	}
-
-	// Deprecated
-	defineComputedProperties() {
-		Object.keys(this.computed()).forEach((prop) => {
-			if (!this.hasOwnProperty(prop)) {
-				console.warn(
-					`[${this.localName}] Using the computed() map for computed properties is deprecated! Please use regular JS getters and return the computed value. See the docs for more info`,
-				);
-				Object.defineProperty(this, prop, {
-					get: () => this.computed()[prop](),
-				});
-			}
-		});
-	}
-
 	/**
 	 * Return a map of events that should be registered on the element.
 	 * eg. { '.link': {
@@ -542,7 +568,14 @@ class BaseElement extends HTMLElement {
 		this.$refs = refsMap;
 	}
 
-	// Helper function for dispatching custom events
+	/**
+	 * Helper function for dispatching custom events
+	 * @param {string} name
+	 * @param {Object} data
+	 * @param {boolean} bubble
+	 * @param {boolean} cancelable
+	 * @param {boolean} composed
+	 */
 	dispatch(name, data, bubble = false, cancelable = false, composed = false) {
 		const event = new CustomEvent(name, {
 			bubbles: bubble,
@@ -553,7 +586,10 @@ class BaseElement extends HTMLElement {
 		this.dispatchEvent(event);
 	}
 
-	// Get the root element
+	/**
+	 * Get the root element
+	 * @returns {HTMLElement}
+	 */
 	getRoot() {
 		return this;
 	}

package/src/StyledElement.js

@@ -2,13 +2,22 @@ import { BaseElement } from './BaseElement.js';
 import { supportsAdoptingStyleSheets, getShadowParentOrBody } from './util/DOMHelper.js';
 export { i18n } from './util/i18n.js';
 
+/**
+ * Options object for the StyledElement
+ * @typedef {Object} StyledElementOptions
+ * @extends BaseElementOptions
+ * @property {boolean} [shadowRender] - 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. Default is `false`
+ * @property {[]} [styles] - Via the styles option you can add multiple styles/stylesheets to your element. Default is `[]`
+ * @property {boolean} [adoptGlobalStyles] - When set to true element-js will look for a style element in the global document with an id of "globalStyles" and apply it before any custom/element styles inside the shadow DOM. Default is `true`
+ */
+
 class StyledElement extends BaseElement {
 	static globalStyles = null;
 
 	static updateGlobalStyles() {
 		// this is a runtime dependency so that every shadow dom can make use of global css
 		// we assume these styles to be inlined into the document
-		StyledElement.globalStyles = document.getElementById('globalStyles');
+		StyledElement.globalStyles = globalThis.document?.getElementById('globalStyles');
 
 		if (StyledElement.globalStyles && StyledElement['globalStyleSheet']) {
 			//updates already adopted global styles
@@ -16,6 +25,9 @@ class StyledElement extends BaseElement {
 		}
 	}
 
+	/**
+	 * @param {StyledElementOptions} options
+	 */
 	constructor(options) {
 		super({
 			deferUpdate: false,
@@ -27,32 +39,36 @@ class StyledElement extends BaseElement {
 		this._styles = [...this._options.styles, ...this.styles()];
 	}
 
+	/**
+	 * Overrides the `connectedCallback` to adopt optional styles when the element is connected
+	 */
 	connectedCallback() {
 		super.connectedCallback();
 
 		if (supportsAdoptingStyleSheets() && this._options.shadowRender) {
 			// adopting does only make sense in shadow dom. Fall back to append for light elements
 			this.adoptStyleSheets();
-		} else if (this._options.shadowRender && window.ShadyCSS !== undefined) {
-			// if shadowRoot is polyfilled we use ShadyCSS to copy scoped styles to <head>
-			window.ShadyCSS.ScopingShim.prepareAdoptedCssText(this._styles, this.localName);
-		}
-
-		// if shadowRoot is polyfilled - scope element template
-		if (window.ShadyCSS !== undefined) {
-			window.ShadyCSS.styleElement(this);
 		}
 	}
 
+	/**
+	 * The styles method is another way to return a list of styles to be adopted when the element is connected.
+	 * You can either provide a list in the constructor options or return it here.
+	 * @returns {string[]}
+	 */
 	styles() {
 		return [];
 	}
 
+	/**
+	 * Overrides the `update` method to adopt optional styles
+	 * @param {PropertyUpdateOptions} options
+	 */
 	update(options) {
 		if (!supportsAdoptingStyleSheets() || this._options.shadowRender === false) {
 			// append stylesheets to template if not already adopted
 			const appendableStyles = [...this._styles];
-			if (this._options.shadowRender && this._options.adoptGlobalStyles && !window.ShadyCSS) {
+			if (this._options.shadowRender && this._options.adoptGlobalStyles) {
 				appendableStyles.unshift(StyledElement.globalStyles?.textContent ?? '');
 			}
 			this.appendStyleSheets(appendableStyles);
@@ -60,6 +76,9 @@ class StyledElement extends BaseElement {
 		super.update(options);
 	}
 
+	/**
+	 * Adopt stylesheets
+	 */
 	adoptStyleSheets() {
 		if (!this.constructor['cssStyleSheets']) {
 			this.constructor['cssStyleSheets'] = this._styles.map((style) => {
@@ -87,7 +106,10 @@ class StyledElement extends BaseElement {
 		];
 	}
 
-	// custom polyfill for constructable stylesheets by appending styles to the end of an element
+	/**
+	 * Custom polyfill for constructable stylesheets by appending styles to the end of an element
+	 * @param {string[]} styles
+	 */
 	appendStyleSheets(styles) {
 		const parentDocument = getShadowParentOrBody(this.getRoot());
 		styles.forEach((style, index) => {
@@ -95,7 +117,7 @@ class StyledElement extends BaseElement {
 
 			// only append stylesheet if not already appended to shadowRoot or document
 			if (!parentDocument.querySelector(`#${identifier}`)) {
-				const styleElement = document.createElement('style');
+				const styleElement = globalThis.document?.createElement('style');
 				styleElement.id = identifier;
 				styleElement.style.display = 'none';
 				styleElement.textContent = style;

package/src/TemplateElement.js

@@ -1,9 +1,18 @@
 import { StyledElement } from './StyledElement.js';
-import { html } from 'lit-html';
-import { render } from 'lit-html/lib/shady-render.js';
+import { html } from './dom-parts/html.js';
+import { render } from './dom-parts/render.js';
 export { i18n } from './util/i18n.js';
 
+/**
+ * Options object for the TemplateElement
+ * @typedef {Object} TemplateElementOptions
+ * @extends StyledElementOptions
+ */
+
 class TemplateElement extends StyledElement {
+	/**
+	 * @param {TemplateElementOptions} options
+	 */
 	constructor(options) {
 		super({
 			deferUpdate: false,
@@ -20,29 +29,40 @@ class TemplateElement extends StyledElement {
 		if (this._options.shadowRender) this.attachShadow({ mode: 'open' });
 	}
 
+	/**
+	 * The template method should be overridden in extending elements and return the template to be rendered to the root
+	 * @returns {TemplateResult}
+	 */
 	template() {
 		return html``;
 	}
 
+	/**
+	 * Override update method to render the template to the root
+	 * @param {PropertyUpdateOptions} options
+	 */
 	update(options) {
 		this.renderTemplate();
 		super.update(options);
 	}
 
+	/**
+	 * Render the template to the root
+	 */
 	renderTemplate() {
 		const template = this._template || this.template();
 		if (typeof template === 'string') {
 			// just a plain string literal. no lit-html required
 			this.getRoot().innerHTML = `${template}`;
 		} else {
-			// render via lit-html
-			render(html` ${template} `, this.getRoot(), {
-				scopeName: this.localName,
-				eventContext: this,
-			});
+			render(template, this.getRoot());
 		}
 	}
 
+	/**
+	 * Get the root element - either the element or the shadow root
+	 * @returns {ShadowRoot | HTMLElement}
+	 */
 	getRoot() {
 		return this.shadowRoot !== null ? this.shadowRoot : this;
 	}