npm - mi-element - Versions diffs - 0.1.0 → 0.3.0 - Mend

mi-element 0.1.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (27) hide show

package/README.md CHANGED Viewed

@@ -2,13 +2,26 @@
 > a lightweight alternative to write web components
-mi-element provides further features to build web applications through
+Only weights 2.3kB minified and gzipped.
+mi-element provides features to build web applications through
 [Web Components][] like:
+- type coercion with setAttribute
 - controllers to hook into the components lifecycle
 - ContextProvider, ContextConsumer for data provisioning from outside of a
   component
 - Store for managing shared state across components
+- Signal for reactive behavior
+The motivation to build this module comes from the confusions around attributes
+and properties. "mi-element" solves this by providing the same results when
+setting objects or functions either through `el.setAttribute(name, value)` or
+properties `el[name] = value`.
+Furthermore all observed attributes have a reactive behavior through the use of
+signals and effects. It implements signals (loosely) following the
+[TC39 JavaScript Signals standard proposal][].
 # Usage
@@ -21,7 +34,7 @@ npm i mi-element
 ```js
 /** @file ./mi-counter.js */
-import { MiElement, define, refsById } from 'mi-element'
+import { MiElement, define, refsById, Signal } from 'mi-element'
 // define your Component
 class MiCounter extends MiElement {
@@ -29,13 +42,12 @@ class MiCounter extends MiElement {
   <style>
     :host { font-size: 1.25rem; }
   </style>
-  <button id="decrement" aria-label="Decrement counter"> - </button>
-  <span id aria-label="Counter value">0</span>
+  <div id aria-label="Counter value">0</div>
   <button id="increment" aria-label="Increment counter"> + </button>
   `
-  // declare reactive attributes
   static get attributes() {
+    // declare reactive attribute(s)
     return { count: 0 }
   }
@@ -44,13 +56,14 @@ class MiCounter extends MiElement {
     // gather refs from template (here by id)
     this.refs = refsById(this.renderRoot)
     // apply event listeners
-    this.refs.button.decrement.addEventListener('click', () => this.count--)
-    this.refs.button.increment.addEventListener('click', () => this.count++)
-  }
-  // called on every change of an observed attributes via `this.requestUpdate()`
-  update() {
-    this.refs.span.textContent = this.count
+    this.refs.increment.addEventListener('click', () => {
+      // change observed and reactive attribute...
+      this.count++
+    })
+    Signal.effect(() => {
+      // ...triggers update on every change of `this.count`
+      this.refs.div.textContent = this.count
+    })
   }
 }
@@ -58,7 +71,7 @@ class MiCounter extends MiElement {
 define('mi-counter', MiCounter)
 ```
-Now use in your HTML
+Now use your now component in your HTML
 ```html
 <body>
@@ -75,16 +88,22 @@ In `./example` you'll find a working sample of a Todo App. Check it out with
 - [lifecycle][docs-lifecycle] mi-element's lifecycle
 - [controller][docs-controller] adding controllers to mi-element to hook into the lifecycle
-- [context][docs-context] Implementation of the [Context Protocol][].
+- [signal][docs-signal] Signals and effect for reactive behavior
 - [store][docs-store] Manage shared state in an application
+- [context][docs-context] Implementation of the [Context Protocol][].
+- [styling][docs-styling] Styling directives for "class" and "style"
 # License
 MIT licensed
-[Context Protocol]: https://github.com/webcomponents-cg/community-protocols/blob/main/proposals/context.md
-[Web Components]: https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements#custom_element_lifecycle_callbacks
 [docs-lifecycle]: https://github.com/commenthol/mi-element/tree/main/packages/mi-element/docs/lifecycle.md
 [docs-controller]: https://github.com/commenthol/mi-element/tree/main/packages/mi-element/docs/controller.md
 [docs-context]: https://github.com/commenthol/mi-element/tree/main/packages/mi-element/docs/context.md
+[docs-signal]: https://github.com/commenthol/mi-element/tree/main/packages/mi-element/docs/signal.md
 [docs-store]: https://github.com/commenthol/mi-element/tree/main/packages/mi-element/docs/store.md
+[docs-styling]: https://github.com/commenthol/mi-element/tree/main/packages/mi-element/docs/styling.md
+[Context Protocol]: https://github.com/webcomponents-cg/community-protocols/blob/main/proposals/context.md
+[Web Components]: https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements#custom_element_lifecycle_callbacks
+[TC39 JavaScript Signals standard proposal]: https://github.com/tc39/proposal-signals
+[krausest/js-framework-benchmark]: https://github.com/krausest/js-framework-benchmark

package/dist/case.js ADDED Viewed

@@ -0,0 +1,3 @@
+const camelToKebabCase = (str = "") => str.replace(/([A-Z])/g, ((_, m) => `-${m.toLowerCase()}`)), kebabToCamelCase = (str = "") => str.toLowerCase().replace(/[-_]\w/g, (m => m[1].toUpperCase()));
+export { camelToKebabCase, kebabToCamelCase };

package/dist/context.js CHANGED Viewed

@@ -1,8 +1,8 @@
-import { isSignalLike, createSignal } from './signal.js';
+import { createSignal, effect } from './signal.js';
 class ContextProvider {
   constructor(host, context, initialValue) {
-    this.host = host, this.context = context, this.state = isSignalLike(initialValue) ? initialValue : createSignal(initialValue),
+    this.host = host, this.context = context, this.state = createSignal(initialValue),
     this.host.addController?.(this);
   }
   hostConnected() {
@@ -11,20 +11,19 @@ class ContextProvider {
   hostDisconnected() {
     this.host.removeEventListener("context-request", this.onContextRequest);
   }
-  set value(newValue) {
-    this.state.value = newValue;
+  set(newValue) {
+    this.state.set(newValue);
   }
-  get value() {
-    return this.state.value;
-  }
-  notify() {
-    this.state.notify();
+  get() {
+    return this.state.get();
   }
   onContextRequest=ev => {
     if (ev.context !== this.context) return;
-    ev.stopPropagation();
-    const unsubscribe = ev.subscribe ? this.state.subscribe(ev.callback) : void 0;
-    ev.callback(this.value, unsubscribe);
+    let unsubscribe;
+    ev.stopPropagation(), ev.subscribe && (unsubscribe = effect((() => {
+      const value = this.get();
+      unsubscribe && ev.callback(value, unsubscribe);
+    }))), ev.callback(this.get(), unsubscribe);
   };
 }

package/dist/element.js CHANGED Viewed

@@ -1,3 +1,7 @@
+import { camelToKebabCase } from './case.js';
+import { createSignal } from './signal.js';
 class MiElement extends HTMLElement {
   #attr={};
   #attrLc=new Map;
@@ -9,19 +13,19 @@ class MiElement extends HTMLElement {
     mode: 'open'
   };
   constructor() {
-    super(), this.#attr = {
-      ...this.constructor.attributes
-    }, this.#observedAttributes();
+    super(), this.#observedAttributes(this.constructor.attributes);
   }
-  #observedAttributes() {
-    for (const [name, val] of Object.entries(this.#attr)) this.#types.set(name, initialType(val)),
-    this.#attrLc.set(name.toLowerCase(), name), Object.defineProperty(this, name, {
+  #observedAttributes(attributes = {}) {
+    for (const [name, value] of Object.entries(attributes)) this.#types.set(name, initialType(value)),
+    this.#attrLc.set(name.toLowerCase(), name), this.#attrLc.set(camelToKebabCase(name), name),
+    this.#attr[name] = createSignal(value), Object.defineProperty(this, name, {
       enumerable: !0,
       get() {
-        return this.#attr[name];
+        return this.#attr[name].get();
       },
       set(newValue) {
-        this.#attr[name] !== newValue && (this.#attr[name] = newValue, this.#changedAttr[name] = newValue,
+        const oldValue = this.#attr[name].get();
+        oldValue !== newValue && (this.#attr[name].set(newValue), this.#changedAttr[name] = oldValue,
         this.requestUpdate());
       }
     });
@@ -41,16 +45,20 @@ class MiElement extends HTMLElement {
   disconnectedCallback() {
     this.#disposers.forEach((remover => remover())), this.#controllers.forEach((controller => controller.hostDisconnected?.()));
   }
-  attributeChangedCallback(name, _oldValue, newValue) {
-    const attr = this.#getName(name), type = this.#getType(attr), _newValue = convertType(newValue, type);
-    this.#attr[attr] = this.#changedAttr[attr] = _newValue, 'Boolean' === type && 'false' === newValue && this.removeAttribute(name),
-    this.requestUpdate();
+  attributeChangedCallback(name, oldValue, newValue) {
+    const attr = this.#getName(name), type = this.#getType(attr);
+    this.#changedAttr[attr] = this[attr], this[attr] = convertType(newValue, type),
+    'Boolean' === type && 'false' === newValue && this.removeAttribute(name), this.requestUpdate();
   }
   setAttribute(name, newValue) {
     const attr = this.#getName(name);
     if (!(attr in this.#attr)) return;
     const type = this.#getType(attr);
-    this.#attr[attr] = this.#changedAttr[attr] = newValue, 'Boolean' === type ? !0 === newValue || '' === newValue ? super.setAttribute(name, '') : super.removeAttribute(name) : [ 'String', 'Number' ].includes(type) || !0 === newValue ? super.setAttribute(name, newValue) : this.requestUpdate();
+    'Boolean' === type ? !0 === newValue || '' === newValue ? super.setAttribute(name, '') : super.removeAttribute(name) : [ 'String', 'Number' ].includes(type) || !0 === newValue ? super.setAttribute(name, newValue) : (this.#changedAttr[attr] = this[attr],
+    this[attr] = newValue, this.requestUpdate());
+  }
+  shouldUpdate(_changedAttributes) {
+    return !0;
   }
   requestUpdate() {
     this.isConnected && requestAnimationFrame((() => {
@@ -61,9 +69,6 @@ class MiElement extends HTMLElement {
     template instanceof HTMLTemplateElement && this.renderRoot.appendChild(template.content.cloneNode(!0));
   }
   render() {}
-  shouldUpdate(_changedAttributes) {
-    return !0;
-  }
   update(_changedAttributes) {}
   on(eventName, listener, node = this) {
     node.addEventListener(eventName, listener), this.#disposers.add((() => node.removeEventListener(eventName, listener)));
@@ -73,9 +78,11 @@ class MiElement extends HTMLElement {
       once: !0
     });
   }
-  dispose(listener) {
-    if ('function' != typeof listener) throw new TypeError('listener must be a function');
-    this.#disposers.add(listener);
+  dispose(...listeners) {
+    for (const listener of listeners) {
+      if ('function' != typeof listener) throw new TypeError('listener must be a function');
+      this.#disposers.add(listener);
+    }
   }
   addController(controller) {
     this.#controllers.add(controller), this.isConnected && controller.hostConnected?.();

package/dist/index.js CHANGED Viewed

@@ -6,6 +6,8 @@ export { esc, escAttr, escHtml } from './escape.js';
 export { refsById, refsBySelector } from './refs.js';
-export { Signal, createSignal, isSignalLike } from './signal.js';
+export { default as Signal } from './signal.js';
-export { Store, subscribeToStore } from './store.js';
+export { Store } from './store.js';
+export { classMap, styleMap } from './styling.js';

package/dist/refs.js CHANGED Viewed

@@ -1,15 +1,15 @@
+import { kebabToCamelCase } from './case.js';
 function refsById(container) {
   const nodes = container.querySelectorAll?.('[id]') || [], found = {};
   for (const node of nodes) found[kebabToCamelCase(node.getAttribute('id') || node.nodeName.toLowerCase())] = node;
   return found;
 }
-const kebabToCamelCase = (str = "") => str.toLowerCase().replace(/[-_]\w/g, (m => m[1].toUpperCase()));
 function refsBySelector(container, selectors) {
   const found = {};
   for (const [name, selector] of Object.entries(selectors)) found[name] = container.querySelector?.(selector);
   return found;
 }
-export { kebabToCamelCase, refsById, refsBySelector };
+export { refsById, refsBySelector };

package/dist/signal.js CHANGED Viewed

@@ -1,24 +1,53 @@
-class Signal {
-  _subscribers=new Set;
-  constructor(initialValue) {
-    this._value = initialValue;
+const context = [];
+class State extends EventTarget {
+  #value;
+  #equals;
+  constructor(value, options) {
+    super();
+    const {equals: equals} = options || {};
+    this.#value = value, this.#equals = equals ?? ((value, nextValue) => value === nextValue);
   }
-  get value() {
-    return this._value;
+  get() {
+    const running = context[context.length - 1];
+    return running && running.add(this), this.#value;
   }
-  set value(newValue) {
-    this._value !== newValue && (this._value = newValue, this.notify());
+  set(nextValue) {
+    this.#equals(this.#value, nextValue) || (this.#value = nextValue, this.dispatchEvent(new CustomEvent('signal')));
   }
-  notify() {
-    for (const callback of this._subscribers) callback(this._value);
+}
+const createSignal = (initialValue, options) => initialValue instanceof State ? initialValue : new State(initialValue, options);
+function effect(cb) {
+  const running = new Set;
+  context.push(running);
+  try {
+    cb();
+  } finally {
+    context.pop();
+  }
+  for (const dep of running) dep.addEventListener('signal', cb);
+  return () => {
+    for (const dep of running) dep.removeEventListener('signal', cb);
+  };
+}
+class Computed {
+  #state;
+  constructor(cb) {
+    this.#state = new State, effect((() => this.#state.set(cb())));
   }
-  subscribe(callback) {
-    return this._subscribers.add(callback), () => {
-      this._subscribers.delete(callback);
-    };
+  get() {
+    return this.#state.get();
   }
 }
-const createSignal = initialValue => new Signal(initialValue), isSignalLike = possibleSignal => 'function' == typeof possibleSignal?.subscribe && 'function' == typeof possibleSignal?.notify && 'value' in possibleSignal;
+var signal = {
+  State: State,
+  createSignal: createSignal,
+  effect: effect,
+  Computed: Computed
+};
-export { Signal, createSignal, isSignalLike };
+export { Computed, State, createSignal, signal as default, effect };

package/dist/store.js CHANGED Viewed

@@ -1,28 +1,10 @@
-import { Signal, isSignalLike } from './signal.js';
+import { State } from './signal.js';
-class Store extends Signal {
-  constructor(actions, initialValue) {
-    super(initialValue);
-    for (const [action, dispatcher] of Object.entries(actions)) this[action] = data => {
-      this.value = dispatcher(data)(this.value);
-    };
+class Store extends State {
+  constructor(actions, initialValue, options) {
+    super(initialValue, options);
+    for (const [action, dispatcher] of Object.entries(actions)) this[action] = data => this.set(dispatcher(data)(this.get()));
   }
 }
-const subscribeToStore = (element, store, propOrSignal) => {
-  if (propOrSignal instanceof Signal || isSignalLike(propOrSignal)) return void element.dispose(store.subscribe((value => {
-    propOrSignal.value = value;
-  })));
-  const keys = Array.isArray(propOrSignal) ? propOrSignal : propOrSignal.split('.').filter(Boolean), last = keys.pop();
-  if (!last) throw TypeError('need prop');
-  let tmp = element;
-  for (const key of keys) {
-    if ('object' != typeof tmp[key]) throw new TypeError(`object expected for property "${key}"`);
-    tmp = tmp[key];
-  }
-  element.dispose(store.subscribe((value => {
-    tmp[last] = value, element.requestUpdate();
-  })));
-};
-export { Store, subscribeToStore };
+export { Store };

package/dist/styling.js ADDED Viewed

@@ -0,0 +1,17 @@
+import { camelToKebabCase } from './case.js';
+const classMap = map => {
+  const acc = [];
+  for (const [name, value] of Object.entries(map ?? {})) value && acc.push(name);
+  return acc.join(' ');
+}, styleMap = (map, options) => {
+  const {unit: unit = "px"} = options || {}, acc = [];
+  for (const [name, value] of Object.entries(map ?? {})) {
+    if (null == value) continue;
+    const _unit = Number.isFinite(value) ? unit : '';
+    acc.push(`${camelToKebabCase(name)}:${value}${_unit}`);
+  }
+  return acc.join(';');
+};
+export { classMap, styleMap };

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "mi-element",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Build lightweight reactive micro web-components",
   "keywords": [],
   "homepage": "https://github.com/commenthol/mi-element/tree/main/packages/mi-element#readme",
@@ -29,6 +29,11 @@
       "development": "./src/element.js",
       "types": "./types/element.d.ts"
     },
+    "./case": {
+      "default": "./dist/case.js",
+      "development": "./src/case.js",
+      "types": "./types/case.d.ts"
+    },
     "./context": {
       "default": "./dist/context.js",
       "development": "./src/context.js",
@@ -54,6 +59,11 @@
       "development": "./src/store.js",
       "types": "./types/store.d.ts"
     },
+    "./styling": {
+      "default": "./dist/styling.js",
+      "development": "./src/styling.js",
+      "types": "./types/styling.d.ts"
+    },
     "./package.json": {
       "default": "./package.json"
     }
@@ -83,8 +93,9 @@
     "vitest": "^2.0.5"
   },
   "scripts": {
-    "all": "npm-run-all lint test build",
-    "build": "rimraf dist && rollup -c && gzip dist/index.min.js && ls -al dist && rimraf dist/index.min.*",
+    "all": "npm-run-all pretty lint test build types",
+    "build": "rimraf dist && rollup -c && gzip -k dist/index.min.js && ls -al dist && rimraf dist/index.min.*",
+    "docs": "cd docs; for f in *.md; do markedpp -s -i $f; done",
     "example": "vite --open /example/",
     "lint": "eslint",
     "pretty": "prettier -w **/*.js",

package/src/case.js ADDED Viewed

@@ -0,0 +1,15 @@
+/**
+ * convert lowerCamelCase to kebab-case
+ * @param {string} str
+ * @returns {string}
+ */
+export const camelToKebabCase = (str = '') =>
+  str.replace(/([A-Z])/g, (_, m) => `-${m.toLowerCase()}`)
+/**
+ * convert kebab-case to lowerCamelCase
+ * @param {string} str
+ * @returns {string}
+ */
+export const kebabToCamelCase = (str = '') =>
+  str.toLowerCase().replace(/[-_]\w/g, (m) => m[1].toUpperCase())

package/src/context.js CHANGED Viewed

@@ -2,7 +2,7 @@
  * @see https://github.com/webcomponents-cg/community-protocols/blob/main/proposals/context.md
  */
-import { createSignal, isSignalLike } from './signal.js'
+import { createSignal, effect } from './signal.js'
 /**
  * @typedef {import('./element.js').HostController} HostController
@@ -25,9 +25,7 @@ export class ContextProvider {
   constructor(host, context, initialValue) {
     this.host = host
     this.context = context
-    this.state = isSignalLike(initialValue)
-      ? initialValue
-      : createSignal(initialValue)
+    this.state = createSignal(initialValue)
     // @ts-expect-error
     this.host.addController?.(this)
   }
@@ -45,24 +43,20 @@ export class ContextProvider {
   /**
    * @param {any} newValue
    */
-  set value(newValue) {
-    this.state.value = newValue
+  set(newValue) {
+    this.state.set(newValue)
   }
   /**
    * @returns {any}
    */
-  get value() {
-    return this.state.value
-  }
-  notify() {
-    this.state.notify()
+  get() {
+    return this.state.get()
   }
   /**
    * @private
-   * @param {ContextRequestEvent} ev
+   * @param {ContextRequestEvent} ev
    */
   onContextRequest = (ev) => {
     if (ev.context !== this.context) {
@@ -70,10 +64,17 @@ export class ContextProvider {
       return
     }
     ev.stopPropagation()
-    const unsubscribe = ev.subscribe
-      ? this.state.subscribe(ev.callback)
-      : undefined
-    ev.callback(this.value, unsubscribe)
+    console.debug('provider.onContextRequest', this.state)
+    let unsubscribe
+    if (ev.subscribe) {
+      unsubscribe = effect(() => {
+        // needed to subscribe to signal
+        const value = this.get()
+        // don't call callback the first time where unsubscribe is not defined
+        if (unsubscribe) ev.callback(value, unsubscribe)
+      })
+    }
+    ev.callback(this.get(), unsubscribe)
   }
 }
@@ -140,6 +141,7 @@ export class ContextConsumer {
   }
   _callback(value, unsubscribe) {
+    console.debug('consumer.callback', { value, unsubscribe })
     if (unsubscribe) {
       if (!this.subscribe) {
         // unsubscribe as we didn't ask for subscription