Merge pull request #3 from efflore/feature/v0.4.0

Feature/v0.4.0

Author: estherbrunner

README.md

@@ -1,28 +1,28 @@
 # ui-element.js
 
-UIElement - minimal reactive framework based on Web Components
+UIElement - the "look ma, no JS framework!" library bringing signals-based reactivity to Web Components
 
 ## What is UIElement?
 
 `UIElement` is a base class for your reactive Web Components. It extends the native `HTMLElement` class and adds 1 public property and 4 methods that allow you to implement inter- and intra-component reactivity with ease.
 
-It will parse attributes in `attributeChangedCallback()` and assign the values to reactive properties according to the mapping to key and primitive type in the `attributeMapping` property of your component. By declaratively setting `static observedAttributes` and `attributeMapping` you will almost never have to override `attributeChangedCallback()`. Your reactive properties will be automatically setup with initial values from attributes.
+It will parse attributes in `attributeChangedCallback()` and assign the values to reactive properties according to the mapping to key and primitive type in the `attributeMapping` property of your component. By declaratively setting `static observedAttributes` and `attributeMapping` you will almost never have to override `attributeChangedCallback()`. Your reactive states will be automatically setup with initial values from attributes.
 
-`UIElement` implements a `Map`-like interface on top of `HTMLElement` to access and modify reactive properties. This allows to use any value as key for reactive properties, as opposed to using direct properties on the element object. This way, we can avoid accidental name clashes with global HTML attributes, JavaScript reserved words or method names and don't have to convert from kebab-case to camelCase and vice versa. The method names `this.has()`, `this.get()`, and `this.set()` feel familar to JavaScript developers and mirror what you already use to access and modify attributes.
+`UIElement` implements a `Map`-like interface on top of `HTMLElement` to access and modify reactive properties. This allows to use any value as key for reactive properties, as opposed to using direct properties on the element object. This way, we can avoid accidental name clashes with global HTML attributes, JavaScript reserved words or method names and don't have to convert from kebab-case to camelCase and vice versa. The method names `this.has()`, `this.get()`, `this.set()` and `this.delete()` feel familar to JavaScript developers and mirror what you already use to access and modify attributes.
 
-In the `connectedCallback()` you setup references to inner elements, add event listeners and pass reactive properties to sub-components. Additionally, for every independent reactive property you define what happens when it changes with `effect()`. `UIElement` will automatically trigger these effects and bundle the surgical DOM updates when the browser refreshes the view.
+In the `connectedCallback()` you setup references to inner elements, add event listeners and pass reactive properties to sub-components. Additionally, for every independent reactive property you define what happens when it changes with `this.effect()`. `UIElement` will automatically trigger these effects and bundle the surgical DOM updates when the browser refreshes the view.
 
 That's all.
 
 ## What is UIElement intentionally not?
 
-UIElement does not do things other full-fledged frontend or full-stack frameworks do.
+UIElement does not do many of the things JavaScript frameworks do.
 
 Most importantly, it does not render components. We suggest, you render components (eighter Light DOM children or Declarative Shadow DOM) on the server side. There are existing solutions like [WebC](https://github.com/11ty/webc) or [Enhance](https://github.com/enhance-dev/enhance) that allow you to declare and render single-file components on the server side with (almost) pure HTML, CSS and JavaScript. UIElement is proven to work with either WebC or Enhance. But you could use any tech stack able to render HTML. There is no magic involved besides the building blocks of any website: HTML, CSS and JavaScript. UIElement does not make any assumptions about the structure of the inner HTML. In fact, it is up to you to reference inner elements and do surgical DOM updates in effects. This also means, there is no new language or format to learn. HTML, CSS and modern JavaScript (ES6) is all you need to know to develop your own web components with UIElement.
 
-UIElement does no routing. It is strictly for single-page applications. But of course, you can reuse the same components on many different pages, effectively creating tailored single-page applications for every pages you want to enhance with rich interactivity. We belive, this is the most efficient way to build rich multi-page applications, as only the scripts for the elements used on the current page are loaded, not a huge bundle for the whole app.
+UIElement does no routing. It is strictly for single-page applications. But of course, you can reuse the same components on many different pages, effectively creating tailored single-page applications for every pages you want to enhance with rich interactivity. We believe, this is the most efficient way to build rich multi-page applications, as only the scripts for the elements used on the current page are loaded, not a huge bundle for the whole app.
 
-UIElement uses no Virtual DOM and doesn't do any dirty-checking or DOM diffing. Consider these approaches by other frameworks as technical debt, not needed anymore.
+UIElement uses no Virtual DOM and doesn't do any dirty-checking or DOM diffing. Consider these approaches by JavaScript frameworks as technical debt, not needed anymore.
 
 ## Getting Started
 
@@ -35,7 +35,7 @@ npm install @efflore/ui-element
 In JavaScript:
 
 ```js
-import UIElement, { effect } from '@efflore/ui-element';
+import UIElement from '@efflore/ui-element';
 
 customElements.define('my-counter', class extends UIElement {
   static observedAttributes = ['value'];
@@ -46,7 +46,7 @@ customElements.define('my-counter', class extends UIElement {
     this.querySelector('.decrement').onclick = () => this.set('value', v => v - 1);
     this.querySelector('.increment').onclick = () => this.set('value', v => v + 1);
 
-    effect(() => this.querySelector('span').textContent = this.get('value'));
+    this.effect(() => this.querySelector('span').textContent = this.get('value'));
   }
 });
 ```
@@ -80,7 +80,7 @@ Important: Make sure you either bundle JavaScript on the server side or referenc
 So, for example, for server side:
 
 ```js
-import UIElement, { effect } from '@efflore/ui-element';
+import UIElement from '@efflore/ui-element';
 
 customElements.define('my-counter', class extends UIElement {
   ...

eslint.config.js

@@ -0,0 +1,9 @@
+// @ts-nocheck
+import globals from "globals";
+import pluginJs from "@eslint/js";
+
+
+export default [
+  {languageOptions: { globals: globals.browser }},
+  pluginJs.configs.recommended,
+];

index.js

@@ -1,6 +1,6 @@
-/* globals HTMLElement, requestAnimationFrame, setTimeout */
-
 /**
+ * @name UIElement
+ * @version 0.4.0
  * @license
  * Copyright 2024 Esther Brunner
  * SPDX-License-Identifier: BSD-3-Clause
@@ -27,59 +27,65 @@ const isFunction = fn => typeof fn === 'function';
 const maybeCall = (fn, args = [], fallback = fn) => isFunction(fn) ? fn.call(...args) : fallback;
 
 // hold the currently active effect
-let pending;
+let computing;
 
-// set up an empty WeakMap to hold the reactivity tree
+// set up an empty WeakMap to hold the reactivity map
 const reactivityMap = new WeakMap();
 
 /**
- * Get the set of effects dependent on a state from the reactivity tree
+ * Get the set of targets dependent on a state from the reactivity map
  * 
- * @param {Function} fn - getter function of the state as key for the lookup
- * @returns {Set} set of effects associated with the state
+ * @param {import("./types").State<any>} state - state object as key for the lookup
+ * @returns {Set} set of targets associated with the state
  */
-const getEffects = fn => {
-  !reactivityMap.has(fn) && reactivityMap.set(fn, new Set());
-  return reactivityMap.get(fn);
+const getTargets = state => {
+  !reactivityMap.has(state) && reactivityMap.set(state, new Set());
+  return reactivityMap.get(state);
 };
 
 /**
- * Define a state and return an object duck-typing Signal.State
+ * Define a state and return an object duck-typing Signal.State instances
  * 
+ * @since 0.1.0
  * @param {any} value - initial value of the state; may be a function to be called on first access
- * @returns {Object} state object with `get` and `set` methods
+ * @returns {import("./types").State<any>} state object with `get` and `set` methods
  * @see https://github.com/tc39/proposal-signals/
  */
-export const cause = value => {
-  const state = {
+const cause = value => {
+  const s = {
     get: () => {
-      pending && getEffects(state).add(pending); // track dependency
-      return maybeCall(value);
+      computing && getTargets(s).add(computing);
+      return value;
     },
-    set: updater => {
-      const old = maybeCall(value);
-      value = maybeCall(updater, [state, old]);
-      !Object.is(value, old) && getEffects(state).forEach(effect => effect()); // trigger effects
+    set: (/** @type {any} */ updater) => {
+      const old = value;
+      value = maybeCall(updater, [s, old], updater);
+      !Object.is(value, old) && getTargets(s).forEach(t => t.get());
     }
   };
-  return state;
+  return s;
 };
 
 /**
- * Define what happens when a reactive dependency changes; function may return a cleanup function to be executed on next tick
+ * Define a derived state and return an object duck-typing Signal.Computed instances
  * 
- * @param {Function} handler - callback function to be executed when a reactive dependency changes
- * @returns {void}
+ * @since 0.4.0
+ * @param {() => any} fn - computation function to be called
+ * @returns {import("./types").Computed<any>} state object with `get` method
+ * @see https://github.com/tc39/proposal-signals/
  */
-export const effect = handler => {
-  const next = () => {
-    pending = next; // register the current effect
-    const cleanup = handler(); // execute handler function
-    isFunction(cleanup) && setTimeout(cleanup); // execute possibly returned cleanup function on next tick
-    pending = null; // unregister the current effect
+const derive = fn => {
+  const d = {
+    get: () => {
+      const prev = computing;
+      computing = d;
+      const value = fn();
+      computing = prev;
+      return value;
+    }
   };
-  requestAnimationFrame(next); // wait for the next animation frame to bundle DOM updates
-}
+  return d;
+};
 
 /* === Default export === */
 
@@ -94,7 +100,8 @@ export default class extends HTMLElement {
   /**
    * Hold [name, type] or just type mapping to be used on attributeChangedCallback
    *
-   * @property {Object} attributeMapping - mapping of attribute names to property keys and types or parser functions
+   * @since 0.2.0
+   * @property {Record<string, import("./types").AttributeParser | import("./types").MappedAttributeParser>} attributeMapping - mapping of attribute names to state keys and types or parser functions
    * @example
    * attributeMapping = {
    *   heading: ['title'],  // attribute mapped to a property with a different name; type 'string' is optional (default)
@@ -106,25 +113,25 @@ export default class extends HTMLElement {
    */
   attributeMapping = {};
 
-  // @private hold states – use `has()`, `get()` and `set()` to access and modify
+  // @private hold states – use `has()`, `get()`, `set()` and `delete()` to access and modify
   #state = new Map();
 
   /**
    * Native callback function when an observed attribute of the custom element changes
    * 
+   * @since 0.1.0
    * @param {string} name - name of the modified attribute
-   * @param {any} old - old value of the modified attribute
-   * @param {any} value - new value of the modified attribute
-   * @returns {void}
+   * @param {string|undefined} old - old value of the modified attribute
+   * @param {string|undefined} value - new value of the modified attribute
    */
   attributeChangedCallback(name, old, value) {
     if (value !== old) {
       const input = this.attributeMapping[name];
       const [key, type] = Array.isArray(input) ? input : [name, input];
       const parser = {
-        boolean: v => typeof v === 'string' ? true : false,
-        integer: v => parseInt(v, 10),
-        number: v => parseFloat(v),
+        boolean: (/** @type {string|undefined} */ v) => typeof v === 'string' ? true : false,
+        integer: (/** @type {string} */ v) => parseInt(v, 10),
+        number: (/** @type {string} */ v) => parseFloat(v),
       };
       const parsed = maybeCall(type, [this, value, old], parser[type] ? parser[type](value) : value);
       this.set(key, parsed);
@@ -134,6 +141,7 @@ export default class extends HTMLElement {
   /**
    * Check whether a state is set
    * 
+   * @since 0.2.0
    * @param {any} key - state to be checked
    * @returns {boolean} `true` if this element has state with the passed key; `false` otherwise
    */
@@ -143,7 +151,8 @@ export default class extends HTMLElement {
 
   /**
    * Get the current value of a state
-   * 
+   *
+   * @since 0.2.0
    * @param {any} key - state to get value from
    * @returns {any} current value of state; undefined if state does not exist
    */
@@ -154,14 +163,34 @@ export default class extends HTMLElement {
   /**
    * Create a state or update its value
    * 
+   * @since 0.2.0
    * @param {any} key - state to set value to
    * @param {any} value - initial or new value; may be a function (gets old value as parameter) to be evaluated when value is retrieved
-   * @returns {void}
    */
   set(key, value) {
     this.has(key)
       ? maybeCall(this.#state.get(key).set, [this, value]) // update state value
-      : this.#state.set(key, cause(value)); // create state
+      : this.#state.set(key, isFunction(value) ? derive(value) : cause(value)); // create state
+  }
+
+  /**
+   * Delete a state, also removing all effects dependent on the state
+   * 
+   * @since 0.4.0
+   * @param {any} key - state to be deleted
+   */
+  delete(key) {
+    this.has(key) && this.#state.delete(key);
+  }
+
+  /**
+   * Define what happens when a reactive state changes
+   * 
+   * @since 0.1.0
+   * @param {() => (() => void) | void} fn - callback function to be executed when a state changes
+   */
+  effect(fn) {
+    requestAnimationFrame(() => derive(fn).get());  // wait for the next animation frame to bundle DOM updates
   }
 
 }

index.min.js

@@ -0,0 +1,72 @@
+// hold the currently active effect
+let computing;
+
+// set up an empty WeakMap to hold the reactivity map
+const reactivityMap = new WeakMap();
+
+/**
+ * Get the set of targets dependent on a state from the reactivity map
+ * 
+ * @param {import("../types").State<any>} state - state object as key for the lookup
+ * @returns {Set} set of targets associated with the state
+ */
+const getTargets = state => {
+  !reactivityMap.has(state) && reactivityMap.set(state, new Set());
+  return reactivityMap.get(state);
+};
+
+/* === Public API === */
+
+/**
+ * Define a state and return an object duck-typing Signal.State instances
+ * 
+ * @since 0.1.0
+ * @param {any} value - initial value of the state; may be a function to be called on first access
+ * @returns {import("../types").State<any>} state object with `get` and `set` methods
+ * @see https://github.com/tc39/proposal-signals/
+ */
+const cause = value => {
+  const s = {
+    get: () => {
+      computing && getTargets(s).add(computing);
+      return value;
+    },
+    set: (/** @type {any} */ updater) => {
+      const old = value;
+      value = typeof updater === 'function' ? updater(old) : updater;
+      !Object.is(value, old) && getTargets(s).forEach(t => t.get());
+    }
+  };
+  return s;
+};
+
+/**
+ * Define a derived state and return an object duck-typing Signal.Computed instances
+ * 
+ * @since 0.4.0
+ * @param {() => any} fn - computation function to be called
+ * @returns {import("../types").Computed<any>} state object with `get` method
+ * @see https://github.com/tc39/proposal-signals/
+ */
+const derive = fn => {
+  const d = {
+    get: () => {
+      const prev = computing;
+      computing = d;
+      const value = fn();
+      computing = prev;
+      return value;
+    }
+  };
+  return d;
+};
+
+/**
+ * Define what happens when a reactive state changes
+ * 
+ * @since 0.1.0
+ * @param {() => void} fn - callback function to be executed when a state changes
+ */
+const effect = fn => derive(fn).get();
+
+export { cause, derive, effect };