@webtides/element-js 1.0.0-alpha.9 → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,319 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](http://keepachangelog.com/) and this project adheres to [Semantic Versioning](http://semver.org/).
+
+<!--
+   PRs should document their user-visible changes (if any) in the
+   Unreleased section, uncommenting the header as necessary.
+-->
+
+<!-- ## Unreleased -->
+<!-- ### Added -->
+<!-- ### Changed -->
+<!-- ### Removed -->
+<!-- ### Fixed -->
+
+## [1.0.0] - 2024-05-24
+
+### Added
+
+-   Added our own versions of directives and template helpers ([#67](https://github.com/webtides/element-js/pull/67))
+-   Added JSDocs for everything in the codebase. This will especially be helpful when using constructor options.
+-   Added state serialization. This improves hydration from SSR a lot. ([#106](https://github.com/webtides/element-js/pull/106))
+-   added declarative shadow dom rendering for template elements
+
+### Changed
+
+-   _BRAKING_ Uses a new custom renderer for the `TemplateElement`. It replaces the old `lit-html` renderer. The API and usage should be exactly the same. The only thing to do/change is the use of the old `lit-html` directives. For detailed instructions see the upgrade guide. ([#67](https://github.com/webtides/element-js/pull/67))
+-   _BREAKING_ `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. ([#60](https://github.com/webtides/element-js/pull/60))
+-   _BREAKING_ Changed `package.json` type to `module`. This should hopefully not break anything. `element-js` is either used directly from the browser or through a bundler. In both cases the added type: module should not matter. ([#64](https://github.com/webtides/element-js/pull/64))
+-   _BRAKING_ Changed the default options when using the `dispatch` helper function. `bubbles`, `cancelable` and `composed` will now be `true` by default.
+-   _BRAKING_ Changed adopting global styles to include ALL global styles. Previously only one inline <style> with the ID of '#globalStyles' would be adopted. For more information see the docs.
+
+### Removed
+
+-   _BREAKING_ Removed the `lit-html` dependency. `element-js` is now officially dependency free! ([#67](https://github.com/webtides/element-js/pull/67))
+-   _BREAKING_ Removed the deprecated `BaseElement` constructor option `childListUpdate`. Please use the "mutationObserverOptions" dictionary instead. See the docs for more info. ([#99](https://github.com/webtides/element-js/pull/99))
+-   _BREAKING_ Removed the `hooks` map in the `BaseElement`. Using the hooks() map for lifecycle hooks is deprecated! Please overwrite the existing lifecycle hook functions. See the docs for more info. ([#99](https://github.com/webtides/element-js/pull/99))
+-   _BREAKING_ Removed the `computed` map in the `BaseElement`. 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. ([#99](https://github.com/webtides/element-js/pull/99))
+-   _BREAKING_ Removed all occurrences of `ShadyCSS` in `StyledElement`. ([#99](https://github.com/webtides/element-js/pull/99))
+-   _BRAKING_ Removed the `i18n` helper function. See CHANGELOG how to implement it yourself or use a third party library.
+
+## [1.0.0-alpha.13] - 2024-05-08
+
+### Fixed
+
+-   catch security errors when `GlobalStylesStore` tries to read css rules from cross-origin stylesheets.
+
+## [1.0.0-alpha.12] - 2024-03-03
+
+### Added
+
+-   added declarative shadow dom rendering for template elements
+
+### Fixed
+
+-   fixed issues with whitespace being returned untrimmed in a template result
+
+## [1.0.0-alpha.11] - 2024-03-13
+
+### Fixed
+
+-   fixed missing return type `string` for the `template()` function in `TemplateElement`
+-   fixed types for the `propertyOptions` option in `BaseElement`
+
+## [1.0.0-alpha.10] - 2024-02-20
+
+### Fixed
+
+-   fixed unsafeHTML not rendering anything when toString was called
+-   fixed using = sign in attribute positions with interpolations
+-   fixed rendering null values in node part positions in SSR
+-   fixed missing .js file extensions
+
+## [1.0.0-alpha.9] - 2024-01-05
+
+### Changed
+
+-   moved DOM methods into connected callbacks to make it safe for the elements to be created in SSR environments
+
+## [1.0.0-alpha.8] - 2024-01-04
+
+### Fixed
+
+-   fixed ChildNodePart not replacing dom nodes from unsafeHTML
+
+## [1.0.0-alpha.7] - 2023-12-19
+
+### Fixed
+
+-   fixed wrong attribute parts for the same name on different elements
+
+## [1.0.0-alpha.6] - 2023-12-18
+
+### Fixed
+
+-   fixed hyphens in attribute names being split in SSR mode
+
+## [1.0.0-alpha.5] - 2023-12-07
+
+### Added
+
+-   Added the /docs directory to the files array in package.json
+-   Added part instances as \_\_part to comment nodes
+
+### Fixed
+
+-   fixed escaped unsafeHTML in SSR mode
+
+## [1.0.0-alpha.4] - 2023-12-01
+
+### Fixed
+
+-   falsy creation of directive parts for non-directive attributes
+-   creating parts with wrong comment marker positions
+
+## [1.0.0-alpha.3] - 2023-12-01
+
+### Added
+
+-   Added state serialization. This improves hydration from SSR a lot. ([#106](https://github.com/webtides/element-js/pull/106))
+
+### Changed
+
+-   _BRAKING_ Changed the default options when using the `dispatch` helper function. `bubbles`, `cancelable` and `composed` will now be `true` by default.
+-   _BRAKING_ Changed adopting global styles to include ALL global styles. Previously only one inline <style> with the ID of '#globalStyles' would be adopted. For more information see the docs.
+
+### Removed
+
+-   _BRAKING_ Removed `i18n` helper function. See CHANGELOG how to implement it yourself or use a third party library.
+
+## [1.0.0-alpha.2] - 2023-08-23
+
+### Added
+
+-   Added JSDocs for everything in the codebase. This will especially be helpful when using constructor options.
+
+## [1.0.0-alpha.1] - 2023-08-15
+
+### Added
+
+-   Added our own versions of directives and template helpers ([#67](https://github.com/webtides/element-js/pull/67))
+
+### Changed
+
+-   _BRAKING_ Uses a new custom renderer for the `TemplateElement`. It replaces the old `lit-html` renderer. The API and usage should be exactly the same. The only thing to do/change is the use of the old `lit-html` directives. For detailed instructions see the upgrade guide. ([#67](https://github.com/webtides/element-js/pull/67))
+-   _BREAKING_ `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. ([#60](https://github.com/webtides/element-js/pull/60))
+-   _BREAKING_ Changed `package.json` type to `module`. This should hopefully not break anything. `element-js` is either used directly from the browser or through a bundler. In both cases the added type: module should not matter. ([#64](https://github.com/webtides/element-js/pull/64))
+
+### Removed
+
+-   _BREAKING_ Removed the `lit-html` dependency. `element-js` is now officially dependency free! ([#67](https://github.com/webtides/element-js/pull/67))
+-   _BREAKING_ Removed the deprecated `BaseElement` constructor option `childListUpdate`. Please use the "mutationObserverOptions" dictionary instead. See the docs for more info. ([#99](https://github.com/webtides/element-js/pull/99))
+-   _BREAKING_ Removed the `hooks` map in the `BaseElement`. Using the hooks() map for lifecycle hooks is deprecated! Please overwrite the existing lifecycle hook functions. See the docs for more info. ([#99](https://github.com/webtides/element-js/pull/99))
+-   _BREAKING_ Removed the `computed` map in the `BaseElement`. 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. ([#99](https://github.com/webtides/element-js/pull/99))
+-   _BREAKING_ Removed all occurrences of `ShadyCSS` in `StyledElement`. ([#99](https://github.com/webtides/element-js/pull/99))
+
+## [0.7.4] - 2023-11-24
+
+### Added
+
+-   storeception (reactive store properties in parent stores)
+-   context injection in shadow elements requests travel though shadow roots
+-   defer element connection (disables client side code until called manually)
+
+### Fixed
+
+-   late context injection if parent mounts after child (loading order)
+-   stores updating elements that want to be updated
+
+## [0.7.3] - 2023-03-07
+
+### Fixed
+
+-   last release was tagged wrong
+
+## [0.7.2] - 2023-03-03
+
+### Fixed
+
+-   watcher callbacks for injected stores
+
+## [0.7.1] - 2023-03-03
+
+### Added
+
+-   Elements are now able to watch Stores
+
+### Fixed
+
+-   Injection of falsy values
+
+## [0.7.0] - 2023-02-13
+
+### Added
+
+-   Dependency Injection via Context Protocol 💉
+-   Provide reactive Properties or entire Stores via: provideProperties() { return { name : value}}
+-   Inject / Request them via injectProperties() { return { name : 'defaultValue'}}
+
+### Changed
+
+-   docs structure
+
+### Fixed
+
+-   Cannot re-render slotted light dom when using the vanilla renderer https://github.com/webtides/element-js/issues/76
+-   adds Vanilla Renderer Tests
+
+## [0.6.2] - 2022-11-18
+
+### FIXED
+
+-   Store always switching to singleProperty Mode if constructed without any arguments.
+
+## [0.6.1] - 2022-11-18
+
+### ADDED
+
+-   Store watch() map to control internal store state scope
+
+## [0.6.0] - 2022-11-17
+
+### ADDED
+
+-   StoreProperty for shared application state
+-   Directives for Vanilla Renderer
+
+## [0.5.0] - 2022-09-13
+
+### Changed
+
+-   improved the performance of the vanilla-renderer
+
+### Removed
+
+-   setting attributes as properties during dom diffing for the vanilla renderer. This is potentially a **breaking** change if you used attributes with the "." (dot) notation
+
+## [0.4.3] - 2022-07-06
+
+### ADDED
+
+-   parse option to propertyOptions that can be either a boolean OR a function for custom parsing
+-   enhance reflect option in propertyOptions that it can also be a function for custom reflection
+
+## [0.4.2] - 2022-02-03
+
+### Fixed
+
+-   vanilla-renderer: fixes attribute comparsion
+
+## [0.4.1] - 2022-02-01
+
+### Fixed
+
+-   refs="id[]" indexing keys not nodes _rolleyes_
+
+### Added
+
+-   refs="id[]" aka possibbility to refrence a list of nodes to the $refs map.
+
+## [0.4.0] - 2022-01-28
+
+### Added
+
+-   a "vanilla" renderer with support for hydration and no dependencies
+
+### Changed
+
+-   uses new @web/test-runner isntead of karma (#27)
+
+## [0.3.3] - 2021-09-22
+
+### Added
+
+-   optional complex event callback notation to support addEventListener options (i.E. for passive Event Listeners )
+-   Example: {listener: () => {}, options: { passive: true } }
+-   docs
+-   tests
+
+## [0.3.2] - 2021-03-09
+
+### Added
+
+-   bundled version of `element-js` to use from a CDN and be able to prototype in tools like CodePen etc.
+
+## [0.3.1] - 2020-12-08
+
+### Fixed
+
+-   i18n fallback values
+
+### Added
+
+-   i18n tests
+
+## [0.3.0] - 2020-07-27
+
+### Added
+
+-   first batch/draft of the documentation
+-   property/attribute reflection via constructor options (see the [Documentation](/docs/README.md#propertyoptions) for more info)
+-   mutationObserverOptions to enable observing subtree mutations (see the [Documentation](/docs/README.md#mutationobserveroptions) for more info)
+
+### Removed
+
+-   `childListUpdate` constructor option has been deprecated and will be removed before `1.0`
+
+## [0.2.0] - 2020-07-01
+
+### Changed
+
+-   uses shady-render instead of render from `lit-html` for rendering templates to be compatible with the shady-css polyfill
+-   refactored and simplified `StyledElement`s handling/loading of style sheets
+
+## [0.1.0] - 2020-06-26
+
+-   initial release

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@webtides/element-js",
-	"version": "1.0.0-alpha.9",
+	"version": "1.0.0",
 	"module": "index.js",
 	"main": "index.js",
 	"type": "module",

package/src/BaseElement.js

@@ -24,7 +24,12 @@ export { toString } from './util/toString.js';
 
 /**
  * Options object for the BaseElement propertyOptions option
- * @typedef {Object} PropertyOptions
+ * @typedef {Object<string, PropertyOption>} PropertyOptions
+ */
+
+/**
+ * Option object for a property of the BaseElement propertyOptions option
+ * @typedef {Object} PropertyOption
  * @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`

package/src/TemplateElement.js

@@ -31,13 +31,13 @@ class TemplateElement extends StyledElement {
 	 * This will attach a shadow DOM if the element is supposed to render in shadow DOM.
 	 */
 	connectedCallback() {
-		if (this._options.shadowRender) this.attachShadow({ mode: 'open' });
+		if (this._options.shadowRender && !this.shadowRoot) this.attachShadow({ mode: 'open' });
 		super.connectedCallback();
 	}
 
 	/**
 	 * The template method should be overridden in extending elements and return the template to be rendered to the root
-	 * @returns {TemplateResult}
+	 * @returns {TemplateResult | string}
 	 */
 	template() {
 		return html``;
@@ -57,12 +57,7 @@ class TemplateElement extends StyledElement {
 	 */
 	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(template, this.getRoot());
-		}
+		render(template, this.getRoot());
 	}
 
 	/**

package/src/dom-parts/ChildNodePart.js

@@ -310,7 +310,7 @@ export class ChildNodePart extends Part {
 			} else if (Array.isArray(value)) {
 				let childNodePart = this.parts[index];
 				if (!childNodePart) {
-					// TODO: this seems not correct :(
+					// TODO: this seems not correct :( (maybe Template vs DOM Parts !?)
 					const templatePartCommentNodes = this.childNodes?.filter(
 						(node) => node && node.nodeType === COMMENT_NODE && node.data === 'template-part',
 					);

package/src/dom-parts/TemplateResult.js

@@ -1,4 +1,4 @@
-import { COMMENT_NODE, getNodePath } from '../util/DOMHelper';
+import { COMMENT_NODE, getNodePath } from '../util/DOMHelper.js';
 import { encodeAttribute, isObjectLike } from '../util/AttributeParser.js';
 import { TemplatePart } from './TemplatePart.js';
 
@@ -29,6 +29,7 @@ export const createTemplateString = (templateStrings, attributePlaceholders = ''
 	// find (match) all elements to identify their attributes
 	template = template.replace(elements, (_, name, attributesString, trailingSlash) => {
 		let elementTagWithAttributes = name + attributesString.replaceAll('\x01', attributePlaceholders).trimEnd();
+		// TODO the closing case is weird.
 		if (trailingSlash.length) elementTagWithAttributes += voidElements.test(name) ? ' /' : '></' + name;
 		// collect all attribute parts so that we can place matching comment nodes
 		const attributeParts = attributesString.replace(attributes, (attribute, name, valueWithQuotes, directive) => {
@@ -48,26 +49,23 @@ export const createTemplateString = (templateStrings, attributePlaceholders = ''
 			}
 			return parts.join('');
 		});
+		// TODO create test to check if lf are in place
 		return `
-				${attributesString.includes('\x01') ? attributeParts : ''}
-				<${elementTagWithAttributes}>
-			`;
+				${attributesString.includes('\x01') ? attributeParts : ''}\n
+				<${elementTagWithAttributes}>\n
+			`.trim();
 	});
 	// replace interpolation placeholders with our indexed markers
 	template = template.replace(partPositions, (partPosition) => {
 		if (partPosition === '\x01') {
 			return `<!--dom-part-${partIndex}--><!--/dom-part-${partIndex++}-->`;
-		}
-		if (partPosition === '\x02') {
+		} else if (partPosition === '\x02') {
 			return `dom-part-${partIndex++}`;
 		}
 	});
-	return `
-		<!--template-part-->
-		${template}
-		<!--/template-part-->
-	`;
-	// TODO: ^ this is actually important because of the whitespace
+	// TODO create test to check if lf are in place
+	// /n is important in the returns as we expect a certain order of text / comments an nodes
+	return `<!--template-part-->\n${template}\n<!--/template-part-->`.trim();
 };
 
 /**
@@ -95,12 +93,16 @@ const getValue = (value) => {
 			return String(value);
 		case 'object':
 			switch (true) {
+				case value === null:
+					return '';
 				case Array.isArray(value):
 					return value.map(getValue).join('');
 				case value instanceof TemplateResult:
 					return value.toString();
 				case value.__unsafeHTML:
 					return value.string;
+				default:
+					console.log('Cannot getValue for', value);
 			}
 			break;
 		case 'function':
@@ -283,8 +285,13 @@ export class TemplateResult {
 			}
 			if (/^dom-part-\d+:/.test(node.data)) {
 				const [_, ...attribute] = node.data.split(':');
-				const [name, initialValue] = attribute.join(':').split('=');
-				parts.push({ type: 'attribute', path: getNodePath(node), name: name, initialValue });
+				const [name, ...initialValue] = attribute.join(':').split('=');
+				parts.push({
+					type: 'attribute',
+					path: getNodePath(node),
+					name: name,
+					initialValue: initialValue.join('='),
+				});
 				continue;
 			}
 			if (/^dom-part-\d+\$/.test(node.data)) {

package/src/dom-parts/html.js

@@ -1,4 +1,4 @@
-import { TemplateResult } from './TemplateResult';
+import { TemplateResult } from './TemplateResult.js';
 
 /**
  * @param {TemplateStringsArray} strings

package/src/dom-parts/render.js

@@ -4,7 +4,12 @@
  * @param {Element} domNode
  */
 const render = (template, domNode) => {
-	template.renderInto(domNode);
+	if (typeof template === 'string') {
+		// just a plain string (or literal)
+		domNode.innerHTML = template;
+	} else {
+		template.renderInto(domNode);
+	}
 };
 
 export { render };

package/src/util/DOMHelper.js

@@ -153,8 +153,7 @@ export const convertStringToHTML = (template) => {
  */
 export const convertStringToTemplate = (string) => {
 	const template = globalThis.document?.createElement('template');
-	// TODO: ensure that SSRed and CSRed templates have the same amount of whitespace text nodes
-	template.innerHTML = string.trimStart().trimEnd();
+	template.innerHTML = string;
 	return template.content;
 };
 

package/src/util/Directive.js

@@ -30,6 +30,13 @@ export class Directive {
  */
 export const defineDirective = (directiveClass) => {
 	return (...values) => {
-		return { directiveClass, values };
+		return {
+			directiveClass,
+			values,
+			toString: () => {
+				const directive = new directiveClass();
+				return directive.stringify(...values);
+			},
+		};
 	};
 };

package/src/util/GlobalStylesStore.js

@@ -53,7 +53,11 @@ class GlobalStylesStore extends Store {
 				if (styleSheet.ownerNode.tagName === 'STYLE') {
 					cssStyleSheet.replaceSync(styleSheet.ownerNode.textContent);
 				} else if (styleSheet.ownerNode.tagName === 'LINK') {
-					Array.from(styleSheet.cssRules).map((rule) => cssStyleSheet.insertRule(rule.cssText));
+					try {
+						Array.from(styleSheet?.cssRules ?? []).map((rule) => cssStyleSheet.insertRule(rule.cssText));
+					} catch (e) {
+						console.error('GlobalStylesStore: cannot read cssRules. Maybe add crossorigin="anonymous" to your style link?', e);
+					}
 				}
 			}
 			cssStyleSheets.push(cssStyleSheet);