@webtides/element-js 1.0.0 → 1.1.0

package/docs/features/store.md

@@ -1,14 +1,8 @@
 #### Shared State / Reactive State / Store
 
-When a certain property in the properties map is an instance of the provided class `Store` it is treated as an
-external `Store`.
-A `Store` can be created outside a components´ scope or in a dedicated Module to keep track of shared Application
-State.
-When a components´ property is an instance of a `Store` the instance will be added as an observer and
-automatically updated when the store ist changed.
+When a certain property in the properties map is an instance of the provided class `Store` it is treated as an external `Store`. A `Store` can be created outside a components´ scope or in a dedicated Module to keep track of shared Application State. When a components´ property is an instance of a `Store` the instance will be added as an observer and automatically updated when the store ist changed.
 
-Instances of Store provide a way to share global state between as many components in an application as you like.
-Shared State can be something very simple as (updated) Viewport Dimensions, Media Changes or complex fetched data from a REST Endpoint.
+Instances of Store provide a way to share global state between as many components in an application as you like. Shared State can be something very simple as (updated) Viewport Dimensions, Media Changes or complex fetched data from a REST Endpoint.
 
 Stores can also be initialized with a primitive value (Numbers, Booleans). Such stores will switch to a single Property Mode and provide direct access tio the property value via the stores valueOf / toString Function for direct access.
 
@@ -16,53 +10,49 @@ Stores can also be initialized with a primitive value (Numbers, Booleans). Such
 
 ```js
 export const simpleStore = new Store({
-	value: 'simple'
-})
+    value: 'simple'
+});
 
 class MoreComplexStore extends Store {
-	properties() {
-		return {
-			storeCount: 1
-		};
-	}
-	get sum() {
-		return this.storeCount + this.argumentCount;
-	}
+    properties() {
+        return {
+            storeCount: 1
+        };
+    }
+    get sum() {
+        return this.storeCount + this.argumentCount;
+    }
 }
 export const exampleStore = new MoreComplexStore({
-	argumentCount: 1
-})
-
+    argumentCount: 1
+});
 
 class MediaStore extends Store {
-	constructor() {
-		super();
-		const mql = window.matchMedia('(max-width: 600px)');
-		mql.onchange = (e) => {
-			this.isMobile = e.matches;
-		}
-	}
-	properties() {
-		return {
-			isMobile: true
-		};
-	}
+    constructor() {
+        super();
+        const mql = window.matchMedia('(max-width: 600px)');
+        mql.onchange = (e) => {
+            this.isMobile = e.matches;
+        };
+    }
+    properties() {
+        return {
+            isMobile: true
+        };
+    }
 }
-export const mediaStore = new MediaStore()
+export const mediaStore = new MediaStore();
 
-export const scrollYStore = new Store(0)
+export const scrollYStore = new Store(0);
 window.addEventListener('scroll', () => {
-	scrollYStore.value = window.scrollY;
+    scrollYStore.value = window.scrollY;
 });
-
-
 ```
 
 ##### MyElement.js
 
-```js 
-
-import { exampleStore, simpleStore, mediaStore } from './store.js'; 
+```js
+import { exampleStore, simpleStore, mediaStore } from './store.js';
 
 export class MyElement extends TemplateElement {
     properties() {
@@ -78,66 +68,61 @@ export class MyElement extends TemplateElement {
         return `
         	<div>Simple Store: ${this.store.value} == "simple" </div>
         	<div>Complex Store: ${this.exampleStore.sum} == 2</div>
-        	<div>Media: ${this.mediaStore.isMobile ? "MOBILE" : "DESKTOP"}</div>
+        	<div>Media: ${this.mediaStore.isMobile ? 'MOBILE' : 'DESKTOP'}</div>
         	<div>Scoll Position: ${this.scrollYStore}</div>
-        	`
+        	`;
     }
 }
 
 export class AnotherElement extends TemplateElement {
     properties() {
         return {
-            store: simpleStore,
+            store: simpleStore
         };
     }
 
     template() {
         return `
         	<div>Simple Store: ${this.store.value} == the same as in MyElement's template.</div>
-        	`
+        	`;
     }
 }
-
-```         
-
+```
 
 ##### storeception
 
 Changes too nested stores will trigger updates and watcher in ParentStore and ultimately transfer to all elements referencing the parent
 
-```js 
-
+```js
 class NestedStore extends Store {
-	properties() {
-		return {
-			nestedCount: 0,
-		};
-	}
+    properties() {
+        return {
+            nestedCount: 0
+        };
+    }
 }
 
 class ParentStore extends Store {
-	properties() {
-		return {
-			count: 0,		
-			nestedStore: new NestedStore(),
-		};
-	}
-
-	requestUpdate() {
-		// will be triggered on count OR nestedStore.nestedCount changes
-	}
-
-	watch() {
-		return {
-			count: (newCount, oldCount) => {
-				// will be triggered on count changes
-			},
-			nestedStore: () => {
-				// will be triggered on nestedStore changes
-			},
-		};
-	}
-}
+    properties() {
+        return {
+            count: 0,
+            nestedStore: new NestedStore()
+        };
+    }
 
-```         
+    requestUpdate() {
+        // will be triggered on count OR nestedStore.nestedCount changes
+    }
 
+    watch() {
+        return {
+            count: (newCount, oldCount) => {
+                // will be triggered on count changes
+            },
+            nestedStore: () => {
+                // will be triggered on nestedStore changes
+            }
+        };
+    }
+}
+```

package/docs/features/templates.md

@@ -135,7 +135,9 @@ Returns:
 
 **spreadAttributes(attributes)**
 
-Renders multiple attributes as key="value" pairs from a map of attributes.
+Renders multiple attributes as key="value" pairs from a map of attributes.  
+Be aware that `spreadAttributes` only works with the given values and does not remember prior iterations.
+Therefore, it will only add / remove values that are present in the given map.
 
 Parameters:
 
@@ -152,6 +154,7 @@ const attrs = { id: 'myElement', ariaLabel: 'Description' };
 const attributeString = spreadAttributes(attrs);
 // When invoked, returns: "id='myElement' aria-label='Description'"
 ```
+ 
 
 ##### Writing custom directives
 

package/docs/features/watch.md

@@ -1,54 +1,47 @@
-
 ### Watch Changes
 
-Alongside defining reactive properties in the `properties()` map, you can define a watcher for every property by
-implementing a `watch()` map in the same manner.
+Alongside defining reactive properties in the `properties()` map, you can define a watcher for every property by implementing a `watch()` map in the same manner.
 
 ```javascript
 export class MyElement extends BaseElement {
-	properties() {
-		return {
-			property: 'I am public & reactive'
-		};
-	}
-
-	watch() {
-		return {
-			property: (newValue, oldValue) => {
-				console.log('property changed', {newValue, oldValue});
-			}
-		};
-	}
+    properties() {
+        return {
+            property: 'I am public & reactive'
+        };
+    }
+
+    watch() {
+        return {
+            property: (newValue, oldValue) => {
+                console.log('property changed', { newValue, oldValue });
+            }
+        };
+    }
 }
 ```
 
-Whenever a property is changed (either from within the element or from outside) it will trigger the callback defined in
-the `watch()` map if present. The callback will be invoked with the old value and the new value as parameters.
+Whenever a property is changed (either from within the element or from outside) it will trigger the callback defined in the `watch()` map if present. The callback will be invoked with the old value and the new value as parameters.
 
-_element-js_ compares values by stringifying them rather than by reference and will only trigger update/render cycles if
-the value actually changed.
+_element-js_ compares values by stringifying them rather than by reference and will only trigger update/render cycles if the value actually changed.
 
-> `array` or `object` data will not trigger changes if nested elements/keys are changed. Also methods like `push()`
-> and `shift()` won't work.
+> `array` or `object` data will not trigger changes if nested elements/keys are changed. Also methods like `push()` and `shift()` won't work.
 
-Non-mutable operations like `map()` and `shift()` and the spread operator will however change the value and trigger an
-update cycle.
+Non-mutable operations like `map()` and `shift()` and the spread operator will however change the value and trigger an update cycle.
 
 ```javascript
 export class MyElement extends BaseElement {
-	properties() {
-		return {
-			items: ['one', 'two']
-		};
-	}
-
-	count() {
-		this.items = [...this.items, 'three'];
-	}
+    properties() {
+        return {
+            items: ['one', 'two']
+        };
+    }
+
+    count() {
+        this.items = [...this.items, 'three'];
+    }
 }
 ```
 
 The spread operator works for objects and arrays.
 
-If you want to make sure that an update will be triggered you can always request it manually by calling
-the `requestUpdate()` method.
+If you want to make sure that an update will be triggered you can always request it manually by calling the `requestUpdate()` method.

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

@@ -75,6 +75,22 @@ In both cases you must now change the imports to our new directives:
 import { unsafeHTML } from '@webtides/element-js/src/dom-parts/directives';
 ```
 
+### element-js@1.1+
+
+since 1.1 its also possible to import directives directly from the modules index
+
+```javascript
+import {
+    classMap,
+    styleMap,
+    when,
+    choose,
+    unsafeHTML,
+    spreadAttributes,
+    optionalAttribute
+} from '@webtides/element-js';
+```
+
 ## Removed childListUpdate option from constructor options
 
 We removed the deprecated `BaseElement` constructor option `childListUpdate`. Please use the "mutationObserverOptions" dictionary instead.

package/docs/guide/guide.md

@@ -1,4 +1,3 @@
-
 ## Guides/Tooling
 
 ### Frontend Stack
@@ -13,10 +12,9 @@ This is an element style guide created and enforced for the purpose of standardi
 
 #### 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.
+-   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:
 
@@ -39,16 +37,12 @@ Example:
 
 ##### 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.
+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.
+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:
 
@@ -72,8 +66,7 @@ card-element
 
 ##### 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:
+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
@@ -91,13 +84,11 @@ card-content
 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 {
-}
+export class ButtonElement extends BaseElement {}
 
 customElements.define('button-element', ButtonElement);
 
-export class MenuElement extends BaseElement {
-}
+export class MenuElement extends BaseElement {}
 
 customElements.define('menu-element', MenuElement);
 ```
@@ -106,7 +97,4 @@ customElements.define('menu-element', MenuElement);
 
 ##### 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.
+> 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/index.js

@@ -4,7 +4,17 @@ import { TemplateElement, html } from './src/TemplateElement.js';
 import { toString } from './src/util/toString.js';
 import { defineElement } from './src/util/defineElement.js';
 import { Store } from './src/util/Store.js';
-import { Directive } from './src/util/Directive.js';
+import {
+    defineDirective,
+    Directive,
+    classMap,
+    styleMap,
+    when,
+    choose,
+    unsafeHTML,
+    spreadAttributes,
+    optionalAttribute,
+} from './src/dom-parts/directives.js';
 
 /**
  * Options object for element-js
@@ -13,4 +23,21 @@ import { Directive } from './src/util/Directive.js';
  * @property {boolean} [observeGlobalStyles] - By default element-js will look for all style elements in the global document and apply them before any custom/element styles inside the shadow DOM. When set to true element-js will also observe the document for any changes regarding styles. This is needed if styles will get added async or late.
  */
 
-export { BaseElement, StyledElement, TemplateElement, Store, Directive, html, toString, defineElement };
+export {
+    BaseElement,
+    StyledElement,
+    TemplateElement,
+    Store,
+    html,
+    toString,
+    defineElement,
+    defineDirective,
+    Directive,
+    classMap,
+    styleMap,
+    when,
+    choose,
+    unsafeHTML,
+    spreadAttributes,
+    optionalAttribute,
+};

package/package.json

@@ -1,64 +1,64 @@
 {
-	"name": "@webtides/element-js",
-	"version": "1.0.0",
-	"module": "index.js",
-	"main": "index.js",
-	"type": "module",
-	"files": [
-		"/docs",
-		"/src",
-		"index.js"
-	],
-	"exports": {
-		".": {
-			"browser": "./index.js",
-			"import": "./index.js",
-			"default": "./index.js"
-		},
-		"./src/*": "./src/*.js",
-		"./src/util/*": "./src/util/*.js",
-		"./src/dom-parts/*": "./src/dom-parts/*.js"
-	},
-	"repository": "https://github.com/webtides/element-js.git",
-	"author": "@webtides",
-	"license": "MIT",
-	"keywords": [
-		"web components",
-		"web component",
-		"components",
-		"component",
-		"custom elements",
-		"elements",
-		"element",
-		"element-js",
-		"shadow-dom"
-	],
-	"dependencies": {},
-	"devDependencies": {
-		"@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",
-		"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}": [
-			"prettier --write",
-			"git add"
-		]
-	},
-	"scripts": {
-		"lint": "eslint index.js 'src/**/*.js'",
-		"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",
-		"start": "web-dev-server --config web-dev-server.config.mjs"
-	}
+    "name": "@webtides/element-js",
+    "version": "1.1.0",
+    "module": "index.js",
+    "main": "index.js",
+    "type": "module",
+    "files": [
+        "/docs",
+        "/src",
+        "index.js"
+    ],
+    "exports": {
+        ".": {
+            "browser": "./index.js",
+            "import": "./index.js",
+            "default": "./index.js"
+        },
+        "./src/*": "./src/*.js",
+        "./src/util/*": "./src/util/*.js",
+        "./src/dom-parts/*": "./src/dom-parts/*.js"
+    },
+    "repository": "https://github.com/webtides/element-js.git",
+    "author": "@webtides",
+    "license": "MIT",
+    "keywords": [
+        "web components",
+        "web component",
+        "components",
+        "component",
+        "custom elements",
+        "elements",
+        "element",
+        "element-js",
+        "shadow-dom"
+    ],
+    "dependencies": {},
+    "devDependencies": {
+        "@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",
+        "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}": [
+            "prettier --write",
+            "git add"
+        ]
+    },
+    "scripts": {
+        "lint": "eslint index.js 'src/**/*.js'",
+        "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",
+        "start": "web-dev-server --config web-dev-server.config.mjs"
+    }
 }