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

package/docs/features/styles.md

@@ -0,0 +1,169 @@
+### Component Styles / CSS
+
+Every _element-js_ element has the ability to load one or more style sheets. Either by adding them to the `styles`option in the `propertyOptions` via the constructor or by implementing a `styles()` method and returning a list of `string` values.
+
+The value of these "style sheets" must always be a `string`.
+
+```javascript
+import { TemplateElement, defineElement, html } from '@webtides/element-js';
+
+const style = 'my-element .element { background: blue; }';
+
+export class StyledElement extends TemplateElement {
+    constructor() {
+        super({ styles: [style] });
+    }
+
+    styles() {
+        return ['my-element .element { color: red; }'];
+    }
+
+    template() {
+        return html` <span class="element">I'm styled!</span> `;
+    }
+}
+
+defineElement('styled-element', StyledElement);
+```
+
+For a better developer experience it is also possible to import real `CSS` files and load them from a separate file instead of cluttering the element with style text.
+
+```javascript
+import { StyleElement, defineElement } from '@webtides/element-js';
+import style from './styled-element.css';
+
+export class StyledElement extends StyleElement {
+    constructor() {
+        super({ styles: [style] });
+    }
+}
+
+defineElement('styled-element', StyledElement);
+```
+
+> Importing `CSS` files or rather `modules` is not currently supported by browsers. It is being worked on - but for now we have to rely on build tools to handle this kind of imports. For a detailed guide on how to build/bundle your elements nicely see [Bundling/Publishing](../README.md#bundlingpublishing).
+
+#### Shadow DOM vs. Light DOM
+
+By default, _element-js_ will render in light DOM. In this case the styling will not be encapsulated, and your element styles could potentially leak out and style any global selectors.
+
+To avoid these problems we highly encourage you to always start your selectors with the element tag name.
+
+```css
+my-element {
+    border: 1px solid blue;
+}
+
+my-element .element {
+    color: red;
+}
+```
+
+When you render an element in Shadow DOM instead you don't have to prefix your selectors with the tag name since Shadow DOM automatically scopes the shadow tree and does not leak any styles to the outside document.
+
+```css
+.element {
+    color: red;
+}
+```
+
+To style the element itself in the parent document you can use the special `:host` selector.
+
+```css
+:host {
+    border: 1px solid blue;
+}
+```
+
+It is also possible to combine the `:host` selector with other matching selectors.
+
+```css
+:host {
+    display: none;
+}
+
+:host([selected]) {
+    display: block;
+}
+```
+
+#### CSS custom properties
+
+Custom properties allow for reusing CSS values throughout a document. To read all about it, see [Using CSS custom properties (variables) - CSS: Cascading Style Sheets | MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties)
+
+The nice thing about custom properties is that they will also take effect inside Shadow DOM elements. They enable therefore a nice and easy way to style certain parts of your element from outside.
+
+```javascript
+import { TemplateElement, defineElement, html } from '@webties/element-js';
+
+export class StyledElement extends TemplateElement {
+    constructor() {
+        super({ shadowRender: true });
+    }
+
+    styles() {
+        return ['.element { color: var(—highlight-color, red); }'];
+    }
+
+    template() {
+        return html` <span class="“element”">I'm highlighted!</span> `;
+    }
+}
+
+defineElement('styled-element', StyledElement);
+```
+
+Users of this element can set the value of `—highlight-color`, using the `styled-element` tag as a CSS selector
+
+```css
+styled-element {
+    -—highlight-color: blue;
+}
+```
+
+#### PostCSS & Plugins
+
+_element-js_ expects the provided CSS to be valid CSS. In recent years developers have been using preprocessing tools like `SCSS` or `LESS` to write more reusable CSS. Pre-processers can however be quite slow during development. Wouldn't it be nice if we could write “normal” CSS again. But with superpowers?
+
+Since we would recommend to always use `PostCSS` and `autoprefixer` anyway - we suggest that you add a few more plugins.
+
+-   postcss-import: [GitHub - postcss/postcss-import: PostCSS plugin to inline @import rules content](https://github.com/postcss/postcss-import)
+-   postcss-nested: [GitHub - postcss/postcss-nested: PostCSS plugin to unwrap nested rules like how Sass does it.](https://github.com/postcss/postcss-nested)
+
+With these plugins, and also CSS custom properties, you will be able to write composable and reusable CSS.
+
+```css
+:root {
+    -—highlight-color: red;
+}
+```
+
+```postcss
+.btn {
+    background: white;
+    border: 1px solid grey;
+    text: var(—highlight-color);
+
+    &.is-active {
+        border: 2px solid black;
+    }
+}
+```
+
+```postcss
+@import './root.css';
+@import './buttons.css';
+
+my-element {
+    -—highlight-color: blue;
+
+    .btn {
+        &:hover {
+            background: var(—highlight-color);
+            text: white;
+        }
+    }
+}
+```
+
+To see how you can integrate PostCSS into your build tools see: [Guides and Tooling](../README.md#bundlingpublishing)

package/docs/features/templates.md

@@ -0,0 +1,308 @@
+### Rendering / TemplateElement
+
+The TemplateElement from _element-js_ can render templates using `lit-html`.
+
+For detailed information see the documentation on [lit-html.polymer-project-org](https://lit-html.polymer-project.org)
+
+> lit-html lets you write HTML templates in JavaScript, then efficiently render and re-render those templates together with data to create and update DOM
+
+To render a template from your element just define a `template()` method and return a `tagged template literal`.
+
+```javascript
+export class MyElement extends TemplateElement {
+    properties() {
+        return {
+            name: 'John'
+        };
+    }
+
+    template() {
+        return html` <span>Hello ${this.name}</span> `;
+    }
+}
+```
+
+#### Shadow DOM vs. Light DOM
+
+By default, _element-js_ will render templates in light DOM. When rendering in light DOM all global styles will be applied to your element as well.
+
+As mentioned before in the constructor options you can set `shadowRender` to `true` . The element will render templates then in the shadow DOM and encapsulate the element from the rest of the document.
+
+#### Data binding
+
+When writing templates vor elements you will often need to access dynamic data as in properties from the element. `tagged template literals` are just enhanced `string literals`. To access variables just use `${}` anywhere inside the string.
+
+#### Template Directives
+
+In `element-js`, directives are powerful utility functions that enhance and simplify the process of writing templates. Here's a detailed breakdown of the available directives:
+
+##### Built-in directives
+
+**classMap(map)**
+
+Maps object properties to class names based on their truthy values.
+
+Parameters:
+
+    map: Object.<string, string | boolean | number> - An object where the keys represent the class names, and the truthy values determine whether the class should be applied.
+
+Returns:
+
+    A string of class names separated by spaces.
+
+Example:
+
+```javascript
+const myMap = { active: true, hidden: false, themeDark: true };
+const classes = classMap(myMap);
+// Returns: "active themeDark"
+```
+
+**styleMap(map)**
+
+Maps object properties to inline styles.
+
+Parameters:
+
+    map: Object.<string, string | undefined | null> - An object where the keys represent the CSS properties and the values represent the CSS values.
+
+Returns:
+
+    A string representation of inline styles.
+
+Example:
+
+```javascript
+const myStyles = { backgroundColor: 'red', display: null };
+const styles = styleMap(myStyles);
+// Returns: "backgroundColor:red;"
+```
+
+**when(condition, trueCase, falseCase)**
+
+Renders one of two template parts based on a condition.
+
+Parameters:
+
+    condition: boolean - The condition to test.
+    trueCase: TemplateResult | string - The value to return if the condition is true.
+    falseCase: TemplateResult | string (optional) - The value to return if the condition is false.
+
+Returns:
+
+    Either the trueCase or falseCase based on the condition.
+
+Example:
+
+```javascript
+const result = when(5 > 3, 'True', 'False');
+// Returns: "True"
+```
+
+**choose(value, cases, defaultCase)**
+
+Selects a template based on a provided value from a map of cases.
+
+Parameters:
+
+    value: string - The value to match against the cases.
+    cases: Object.<string, TemplateResult | string> - A map of values to templates.
+    defaultCase: TemplateResult | string (optional) - The default template to return if no cases match.
+
+Returns:
+
+    The matching case's template or the defaultCase if none match.
+
+Example:
+
+```javascript
+const myCases = { one: 'First', two: 'Second' };
+const chosen = choose('two', myCases, 'Unknown');
+// Returns: "Second"
+```
+
+**unsafeHTML(string)**
+
+Renders a provided string as raw HTML instead of sanitized text. Note: Use with caution, as this can expose vulnerabilities to cross-site scripting (XSS) attacks.
+
+Parameters:
+
+    string: string - The raw HTML string to render.
+
+Returns:
+
+    A function that, when invoked, returns the HTML content.
+
+**spreadAttributes(attributes)**
+
+Renders multiple attributes as key="value" pairs from a map of attributes.
+
+Parameters:
+
+    attributes: Object.<string, any> - The attributes map.
+
+Returns:
+
+    A function that, when invoked, returns a string of attributes.
+
+Example:
+
+```javascript
+const attrs = { id: 'myElement', ariaLabel: 'Description' };
+const attributeString = spreadAttributes(attrs);
+// When invoked, returns: "id='myElement' aria-label='Description'"
+```
+
+##### Writing custom directives
+
+Directives in `element-js` are just functions. They accept parameters and return values that manipulate or produce templates or strings.
+
+To write a custom directive:
+
+    Define a Function: This function will describe what your directive does. The function should return either a template, string, or another function based on its parameters.
+
+```javascript
+const visibility = (isVisible) => {
+    return isVisible ? '' : 'style="display: none;"';
+};
+```
+
+Use your custom directive in your templates.
+
+```javascript
+function template() {
+    return html` <div ${visibility(false)}>This div will be hidden.</div> `;
+}
+```
+
+Remember, the power of directives is in their simplicity. They allow you to encapsulate logic in a function and reuse that logic across multiple templates.
+
+#### Slots
+
+Slots are a very powerful feature when using shadow DOM. By providing slots your elements can accept child elements from the light DOM and have them placed in a specified location inside your elements tree. The slotted content will still belong to the document and therefore also be styled by the document level styles.
+
+With this pattern you can build things like Modals, Dialogs, etc. where can encapsulate all the behaviour in the Shadow DOM and let the user pass any content inside the element.
+
+```javascript
+export class ModalElement extends TemplateElement {
+    template() {
+        return html`
+            <div class="backdrop">
+                <div class="header">
+                    <slot name="header"></slot>
+                </div>
+                <div class="content">
+                    <slot></slot>
+                </div>
+                <div class="footer">
+                    <slot name="footer"></slot>
+                </div>
+            </div>
+        `;
+    }
+}
+```
+
+When the user (the using developer of the element) passes any content to the element it will be placed instead of the default slot inside the `div.content`.
+
+```html
+<modal-element>
+    <p>I am modal content!</p>
+</modal-element>
+```
+
+Slots can also be named so that you can have multiple different slots.
+
+```html
+<modal-element>
+    <p>I am modal content!</p>
+    <button slot="footer">OK</button>
+</modal-element>
+```
+
+Any elements that don't have a slot name will be slotted into the default slot.
+
+#### Complex Template structures
+
+In the examples above we have only seen very simple templates. In real elements you will likely have much more complicated views and your `template()` will start to get messy and hard to read/parse.
+
+Lets look at a slightly more advanced element
+
+```javascript
+export class FormControl extends TemplateElement {
+    properties() {
+        return {
+            label: '',
+            name: '',
+            helpMessage: ''
+        };
+    }
+
+    template() {
+        return html`
+            ${this.label ? html` <label for="input-${this.name}"> ${this.label} </label> ` : ''}
+            <div class="control">
+                <input id="input-${this.name}" name="${this.name}" aria-describedby="${this.name}-help" />
+            </div>
+            ${this.helpMessage ? html` <span id="${this.name}-help"> ${this.helpMessage} </span> ` : ''}
+        `;
+    }
+}
+```
+
+Although we still left out some very important things the template starts to get complicated. To clean this up we can improve the readability by implementing parts of the template in dedicated template functions
+
+```javascript
+export class FormControl extends TemplateElement {
+    properties() {
+        return {
+            label: '',
+            name: '',
+            helpMessage: ''
+        };
+    }
+
+    template() {
+        return html`
+            ${this.labelTemplate()}
+            <div class="control">${this.fieldTemplate()}</div>
+            ${this.helpTemplate()}}
+        `;
+    }
+
+    labelTemplate() {
+        if (!this.label) return null;
+        return html` <label for="input-${this.name}"> ${this.label} </label> `;
+    }
+
+    fieldTemplate() {
+        return html` <input id="input-${this.name}" name="${this.name}" aria-describedby="${this.name}-help" /> `;
+    }
+
+    helpTemplate() {
+        if (!this.helpMessage) return null;
+        return html` <span id="${this.name}-help"> ${this.helpMessage} </span> `;
+    }
+}
+```
+
+#### SSR (Server side rendering)
+
+The templates you write for _element-js_ can easily be rendered on the server or any other environment different from the browser (like Service Workers, Node, etc.). _element-js_ uses special markers (as comments) in the HTML to track positions of control flow and interpolations. When elements get connected in the browser, they don't have to render the templates again. They only need to hydrate.
+
+##### Hydration
+
+When you render templates on the server, _element-js_ can efficiently hydrate elements. It uses the existing rendered templates and only adds event listeners and other things that only work in browser environments. One important piece of hydration is the state of the elements. It is not possible to embed the state into the server rendered templates. _element-js_ therefore uses a global JSON object where all elements (and stores) will serialize their state. If such an object is found upon connection of an element, it will restore its state.
+
+> The state serialization is not enabled by default. Currently most _element-js_ elements only render in the browser (client side). This might change in the future as more and more applications and elements will get rendered server side.
+
+To enable state serialization you can add the following (inline, sync) script block to yor HTML.
+
+```html
+<script>
+    /** @type {ElementJsConfig} */
+    globalThis.elementJsConfig = {
+        serializeState: true
+    };
+</script>
+```

package/docs/features/watch.md

@@ -0,0 +1,54 @@
+
+### 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.
+
+```javascript
+export class MyElement extends BaseElement {
+	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.
+
+_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.
+
+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'];
+	}
+}
+```
+
+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.