Merge pull request #11 from efflore/feature/v0.7.3

Feature/v0.7.3

Author: estherbrunner

README.md

@@ -2,7 +2,7 @@
 
 UIElement - the "look ma, no JS framework!" library bringing signals-based reactivity to vanilla Web Components
 
-Version 0.7.2
+Version 0.7.3
 
 ## What is UIElement?
 
@@ -16,7 +16,7 @@ In the `connectedCallback()` you setup references to inner elements, add event l
 
 `UIElement` is fast. In fact, faster than any JavaScript framework. Only direct fine-grained DOM updates in vanilla JavaScript can beat its performance. But then, you have no loose coupling of components and need to parse attributes and track changes yourself. This tends to get tedious and messy rather quickly. `UIElement` provides a structured way to keep your components simple, consistent and self-contained.
 
-`UIElement` is tiny. 1 kB gzipped over the wire. And it has zero dependiences. If you want to understand how it works, you have to study the source code of [one single file](./index.js).
+`UIElement` is tiny. 889 bytes gzipped over the wire. And it has zero dependiences. If you want to understand how it works, you have to study the source code of [one single file](./index.js).
 
 That's all.
 
@@ -174,10 +174,10 @@ class MotionContext extends UIElement {
   connectedCallback() {
     const mql = matchMedia('(prefers-reduced-motion)');
     this.set('reduced-motion', mql.matches);
+    super.connectedCallback();
     mql.onchange = e => this.set('reduced-motion', e.matches);
   }
 }
-
 MotionContext.define('motion-context');
 ```
 
@@ -190,16 +190,16 @@ class MyAnimation extends UIElement {
   static consumedContexts = ['reduced-motion'];
 
   connectedCallback() {
+    super.connectedCallback();
     effect(() => this.get('reduced-motion') ? subtleFadeIn() : pulsateAndMoveAround());
   }
 }
-
 MyAnimation.define('my-animation');
 ```
 
 ### Scheduling and Cleanup
 
-If you use `effect()` with a callback function like `() => doMyEffectWork()`, it will do all work synchronously in the tracking phase of the effect. That might not be ideal for several reasons:
+If you use `effect()` with a callback function like `() => doMyEffectWork()`, it will do all work synchronously. That might not be ideal for several reasons:
 
 - If effect work is expensive and takes more time than a single tick, not all DOM updates of the effect might happen concurrently.
 - If you `set()` a signal which is used in the effect, you risk producing an infite loop.
@@ -246,7 +246,7 @@ It consists of three functions:
 - `derive()` returns a getter function for the current value of the derived computation
 - `effect()` accepts a callback function to be exectuted when used signals change
 
-Cause & Effect is possibly the simplest way to turn JavaScript into a reactive language – with just 385 bytes gezipped code. By default, Cause & Effect doesn't do any memoization for derived signals but recalculates their current value each time. Contrary to general expectations, this seems to be faster in most cases. If you however are performing expensive work in computed signals or rely on count of the execution times, you should turn memoization on, by setting the second parameter of `derive()` to `true`.
+Cause & Effect is possibly the simplest way to turn JavaScript into a reactive language – with just 386 bytes gezipped code. By default, Cause & Effect doesn't do any memoization for derived signals but recalculates their current values each time. Contrary to general expectations, this seems to be faster in most cases. If you however are performing expensive work in computed signals or rely on the count of execution times, you should turn memoization on, by setting the second parameter of `derive()` to `true`.
 
 #### Usage Example
 
@@ -292,7 +292,16 @@ The last option comes with a bit more library code (around 1.6 kB gzipped), but
 <script type="module">
   import { component, asInteger } from './component';
 
-  component('my-counter', { value: v => asInteger }, (el, my) => {
+  component('my-counter', {
+    attributeMap: { // static observedAttributes is derived from the keys of optional `attributeMap` object
+      value: v => asInteger
+    },
+    consumedContexts: [], // for static consumedContexts an array of keys can be provided optionally
+    providedContexts: [], // for static providedContexts an array of keys can be provided optionally
+  },
+  (el, my) => {
+    // `el` is `this` of your custom element
+    // `my` is a UI reference of your custom element
     my.first('.decrement').on('click', () => el.set('value', v => --v));
     my.first('.increment').on('click', () => el.set('value', v => ++v));
     my.first('span').text('value');
@@ -320,7 +329,7 @@ import { component, ui } from './component';
 component('my-counter', {}, (el, my) => {
   // third parameter of component is called in connectedCallback()
   // `el` is `this` of your custom element
-  // `my` is a UI reference function to the element with convenience methods to query sub-elements, bind events, and auto-create effects
+  // `my` is a UI reference of your custom the element with convenience methods to query sub-elements, bind events, and auto-create effects
 
   // console.log(my()); // calling the UI reference returns the native DOM element
   const count = my.first('.count'); // first does querySelector and returns a UI reference
@@ -348,12 +357,14 @@ component('my-counter', {}, (el, my) => {
 
 On `UI` reference objects you can call these utility methods:
 
-- `ref.text()` preserves comment nodes in contrast to `element.textContent` assignments
-- `ref.prop()` sets or deletes a property on an element
-- `ref.attr()` sets or removes an attribute on an element
-- `ref.bool()` toggles a boolean attribute on an element
-- `ref.class()` adds or removes a class on an element
-- `ref.style()` sets or removes a style property on an element
+- `ref()` returns the native element
+- `ref.setText()` replaces text content of element while preserving comment nodes; to be used in effects
+- `ref.text()` auto-effect to replace text content while preserving comment nodes in contrast to `element.textContent` assignments
+- `ref.prop()` auto-effect to set or delete a property on an element
+- `ref.attr()` auto-effect to set or remove an attribute on an element
+- `ref.bool()` auto-effect to toggle a boolean attribute on an element
+- `ref.class()` auto-effect to add or remove a class on an element
+- `ref.style()` auto-effect to set or remove a style property on an element
 
 [Source](./component.js)
 
@@ -370,6 +381,7 @@ class MyElement extends DebugElement {
   connectedCallback() {
     this.set('debug', true); // will enable debugging for all instances
     // use the 'debug' boolean attribute to enable debugging just for that specific instance
+    super.connectedCallback(); // for context provider / consumer + debug logging
     /* ... */
   }
 }
@@ -399,6 +411,7 @@ import VisibilityObserver from './src/lib/visibility-observer';
 class MyAnimation extends UIElement {
 
   connectedCallback() {
+    super.connectedCallback(); // needed if you use context provider or consumer
     this.visibilityObserver = new VisibilityObserver(this); // sets and updates 'visible' state on `this`
     effect(() => this.get('visible') ? startAnimation() : stopAnimation());
   }

cause-effect.js

@@ -31,7 +31,7 @@ const isState = (value) => isFunction(value) && isFunction(value.set);
  *
  * @since 0.1.0
  * @param {any} value - initial value of the state; may be a function for derived state
- * @returns {UIState} getter function for the current value with a `set` method to update the value
+ * @returns {UIState<T>} getter function for the current value with a `set` method to update the value
  */
 const cause = (value) => {
     const state = () => {
@@ -52,9 +52,9 @@ const cause = (value) => {
  * Create a derived state from an existing state
  *
  * @since 0.1.0
- * @param {() => any} fn - existing state to derive from
+ * @param {() => T} fn - existing state to derive from
  * @param {boolean} [memo=false] - whether to use memoization
- * @returns {UIComputed<any>} derived state
+ * @returns {UIComputed<T>} derived state
  */
 const derive = (fn, memo = false) => {
     let value;
@@ -90,7 +90,7 @@ const effect = (fn) => {
         active = next;
         const cleanup = fn((element, domFn) => {
             !targets.has(element) && targets.set(element, new Set());
-            targets.get(element).add(domFn);
+            targets.get(element)?.add(domFn);
         });
         for (const domFns of targets.values()) {
             for (const domFn of domFns)