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

package/src/util/DOMHelper.js

@@ -6,10 +6,12 @@ export const ATTRIBUTE_NODE = 2;
 export const TEXT_NODE = 3;
 /* A Comment node, such as <!-- … --> */
 export const COMMENT_NODE = 8;
+/* A Document Fragment, a document without a parent */
+export const DOCUMENT_FRAGMENT_NODE = 11;
 
 /**
- * Gets list of (childNode) indexes for the given node
- * @param node
+ * Gets a list of (childNode) indexes for the given node
+ * @param {Node} node
  * @return {number[]}
  */
 export const getNodePath = (node) => {
@@ -23,6 +25,11 @@ export const getNodePath = (node) => {
 	return path;
 };
 
+/**
+ * Get a list of all parent nodes up the DOM tree
+ * @param {Node} domNode
+ * @returns {Node[]}
+ */
 export function getAllParentNodes(domNode) {
 	let node = domNode.parentElement;
 	let parents = [];
@@ -34,7 +41,12 @@ export function getAllParentNodes(domNode) {
 	return parents;
 }
 
-// https://stackoverflow.com/questions/27453617/how-can-i-tell-if-an-element-is-in-a-shadow-dom
+/**
+ * Gets the parent/root element of a shadow root or the global document body if not in shadow root.
+ * https://stackoverflow.com/questions/27453617/how-can-i-tell-if-an-element-is-in-a-shadow-dom
+ * @param {Node} element
+ * @returns {ShadowRoot | HTMLElement}
+ */
 export function getShadowParentOrBody(element) {
 	if (element instanceof ShadowRoot) {
 		return element;
@@ -50,6 +62,11 @@ export function getShadowParentOrBody(element) {
 
 // TODO: add function for getClosestParentOfNodeType('custom-element')
 
+/**
+ * Get the closest/first parent node that is a custom element
+ * @param {Node} domNode
+ * @returns {Node}
+ */
 export function getClosestParentCustomElementNode(domNode) {
 	const customElementParents = getAllParentNodes(domNode).filter((node) => {
 		return node.localName && node.localName.indexOf('-') !== -1;
@@ -58,19 +75,31 @@ export function getClosestParentCustomElementNode(domNode) {
 	return customElementParents.pop();
 }
 
+/**
+ * Checks whether two nodes are of the same node type
+ * @param {Node} nodeA
+ * @param {Node} nodeB
+ * @returns {boolean}
+ */
 export function isOfSameNodeType(nodeA, nodeB) {
 	if (!nodeA && !nodeA.localName) return false;
 	if (!nodeB && !nodeB.localName) return false;
 	return nodeA.localName === nodeB.localName;
 }
 
-export const supportsAdoptingStyleSheets = () =>
-	'adoptedStyleSheets' in Document.prototype && 'replace' in CSSStyleSheet.prototype;
-
-// for IE11 we are using the ShadyDOM Polyfill. With the polyfill we cannot append stylesheets to the shadowRoot
-export const supportsAppendingStyleSheets = !window.ShadyDOM;
+/**
+ * Checks if adopting style sheets is supported in browser
+ * @returns {boolean}
+ */
+export const supportsAdoptingStyleSheets = () => {
+	return 'adoptedStyleSheets' in Document.prototype && 'replace' in CSSStyleSheet.prototype;
+};
 
-// better hasChildNodes check because the native check will also count for empty whitespace as child nodes... :(
+/**
+ * Better implementation of hasChildNodes check because the native check will also count for empty whitespace as child nodes... :(
+ * @param {Node} node
+ * @returns {boolean}
+ */
 export const hasChildNodes = (node) => {
 	const childNodesLength = node.childNodes.length;
 
@@ -86,7 +115,7 @@ export const hasChildNodes = (node) => {
 };
 
 /**
- * Parses the given template string and returns a real DOM element.
+ * Parses the given string as HTML template and returns a real DOM element
  * @param {string} template
  * @returns {HTMLElement}
  */
@@ -97,8 +126,8 @@ export const convertStringToHTML = (template) => {
 };
 
 /**
- * Parses the given string and returns a DocumentFragment
- * which contains the DOM subtree representing the <template> element's template contents.
+ * Parses the given string and returns a DocumentFragment which contains the DOM subtree
+ * representing the <template> element's template contents.
  * @param {string} string
  * @return {DocumentFragment}
  */
@@ -111,8 +140,8 @@ export const convertStringToTemplate = (string) => {
 
 /**
  * Diff the attributes for a live DOM element against a template DOM element
- * @param  {Element} templateElement The new template
- * @param  {Element} domElement The existing DOM node
+ * @param {Element} templateElement - The new template
+ * @param {Element} domElement - The existing DOM node
  */
 export const diffAttributes = function (templateElement, domElement) {
 	// remove or update previous attributes

package/src/util/Directive.js

@@ -2,6 +2,9 @@ export class Directive {
 	/** @type {Element} */
 	node = undefined;
 
+	/**
+	 * @param {Node} node
+	 */
 	constructor(node) {
 		this.node = node;
 	}
@@ -10,6 +13,16 @@ export class Directive {
 	 * @abstract
 	 */
 	update() {}
+
+	// TODO: this is somewhat custom... maybe we could set the initial values in the constructor and then simply override the default toString() method?!
+	/**
+	 * Implement the stringify method and return a string for rendering the directive in SSR mode
+	 * @param {...any} values
+	 * @returns {string}
+	 */
+	stringify(...values) {
+		return '';
+	}
 }
 
 /**

package/src/util/Store.js

@@ -1,11 +1,14 @@
 import { isObjectLike, deepEquals } from './AttributeParser.js';
-import { BaseElement } from '../BaseElement';
+import { BaseElement } from '../BaseElement.js';
 
 export class Store {
 	_observer = new Set();
 	_singlePropertyMode = false;
 	_state = {};
 
+	/**
+	 * @param {* | object} value
+	 */
 	constructor(value) {
 		// wrap primitives with a generic "value" field to generate getter and setter
 		this._singlePropertyMode = arguments.length > 0 && !isObjectLike(value);
@@ -33,6 +36,11 @@ export class Store {
 		});
 	}
 
+	/**
+	 * Properties to be defined and assigned on the store. Can be overridden in extended classes.
+	 * Properties defined here will also trigger an update cycle when changed.
+	 * @return {{}}
+	 */
 	properties() {
 		return {};
 	}
@@ -40,34 +48,47 @@ export class Store {
 	/**
 	 * When a property as the key was changed in the store, the callback function defined as value
 	 * will be called with `newValue` and `oldValue`
-	 * eg. { property: (oldValue, newValue) => { console.log('property changed!, oldValue, newValue); } }
 	 * @return {{}}
 	 */
 	watch() {
 		return {};
 	}
 
+	/**
+	 * Overrides `valueOf` to automatically return .value
+	 * @returns {* | {}}
+	 */
 	valueOf() {
 		return this._singlePropertyMode ? this._state.value : this._state;
 	}
 
+	/**
+	 * Overrides `toString` to automatically return .value
+	 * @returns {string}
+	 */
 	toString() {
 		return `${this._singlePropertyMode ? this._state.value : this._state}`;
 	}
 
 	/**
-	 * @param {BaseElement|Function} observer
+	 * Add an observer
+	 * @param {BaseElement | Function} observer
 	 */
 	subscribe(observer) {
 		this._observer.add(observer);
 	}
+
 	/**
-	 * @param {BaseElement|Function} observer
+	 * Remove an observer
+	 * @param {BaseElement | Function} observer
 	 */
 	unsubscribe(observer) {
 		this._observer.delete(observer);
 	}
 
+	/**
+	 * Request and batch an asynchronous update cycle
+	 */
 	requestUpdate() {
 		this._observer.forEach(async (observer) => {
 			if (observer instanceof BaseElement) {

package/src/util/defineElement.js

@@ -1,7 +1,7 @@
 /**
  * Wrapper for defining custom elements so that registering an element multiple times won't crash
- * @param name for the tag
- * @param constructor for the custom element
+ * @param {string} name - name for the element tag
+ * @param {CustomElementConstructor} constructor for the custom element
  */
 export function defineElement(name, constructor) {
 	try {

package/src/util/i18n.js

@@ -1,9 +1,9 @@
 /**
  * Retrieves a translated key from a dictionary on the window object
  * Example: ${i18n('CustomElement.buttonLabel', 'Label')}
- * @param key to be translated
- * @param fallback to be used if key is not defined
- * @return String of the translated key or fallback or original key
+ * @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 {

package/src/util/toString.js

@@ -1,8 +1,8 @@
 /**
  * Little wrapper function for JSON.stringify() to easily convert objects and arrays to strings
  * to be able to set them as attributes on custom elements
- * @param value to be stringified
- * @return String of the stringified value
+ * @param {object | array} value - to be stringified
+ * @return {string}
  */
 export function toString(value) {
 	try {