mi-element 0.3.0 → 0.3.1

package/README.md

@@ -86,7 +86,7 @@ In `./example` you'll find a working sample of a Todo App. Check it out with
 
 # Documentation
 
-- [lifecycle][docs-lifecycle] mi-element's lifecycle
+- [element][docs-element] mi-element's lifecycle
 - [controller][docs-controller] adding controllers to mi-element to hook into the lifecycle
 - [signal][docs-signal] Signals and effect for reactive behavior
 - [store][docs-store] Manage shared state in an application
@@ -97,7 +97,7 @@ In `./example` you'll find a working sample of a Todo App. Check it out with
 
 MIT licensed
 
-[docs-lifecycle]: https://github.com/commenthol/mi-element/tree/main/packages/mi-element/docs/lifecycle.md
+[docs-element]: https://github.com/commenthol/mi-element/tree/main/packages/mi-element/docs/element.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

package/dist/element.js

@@ -16,19 +16,22 @@ class MiElement extends HTMLElement {
     super(), this.#observedAttributes(this.constructor.attributes);
   }
   #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].get();
-      },
-      set(newValue) {
-        const oldValue = this.#attr[name].get();
-        oldValue !== newValue && (this.#attr[name].set(newValue), this.#changedAttr[name] = oldValue, 
-        this.requestUpdate());
-      }
-    });
+    for (const [name, value] of Object.entries(attributes)) {
+      const initial = initialValueType(value);
+      this.#types.set(name, initial.type), this.#attrLc.set(name.toLowerCase(), name), 
+      this.#attrLc.set(camelToKebabCase(name), name), this.#attr[name] = createSignal(initial.value), 
+      Object.defineProperty(this, name, {
+        enumerable: !0,
+        get() {
+          return this.#attr[name].get();
+        },
+        set(newValue) {
+          const oldValue = this.#attr[name].get();
+          oldValue !== newValue && (this.#attr[name].set(newValue), this.#changedAttr[name] = oldValue, 
+          this.requestUpdate());
+        }
+      });
+    }
   }
   #getName(name) {
     return this.#attrLc.get(name) || name;
@@ -54,7 +57,7 @@ class MiElement extends HTMLElement {
     const attr = this.#getName(name);
     if (!(attr in this.#attr)) return;
     const type = this.#getType(attr);
-    '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], 
+    '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) {
@@ -66,7 +69,7 @@ class MiElement extends HTMLElement {
     }));
   }
   addTemplate(template) {
-    template instanceof HTMLTemplateElement && this.renderRoot.appendChild(template.content.cloneNode(!0));
+    template instanceof HTMLTemplateElement ? this.renderRoot.appendChild(template.content.cloneNode(!0)) : console.warn('template is not a HTMLTemplateElement');
   }
   render() {}
   update(_changedAttributes) {}
@@ -99,7 +102,33 @@ const define = (name, element, options) => {
   if ('string' != typeof element.template) return;
   const el = document.createElement('template');
   el.innerHTML = element.template, element.template = el;
-}, initialType = value => toString.call(value).slice(8, -1), convertType = (any, type) => {
+}, initialValueType = value => {
+  switch (value) {
+   case Boolean:
+    return {
+      value: void 0,
+      type: 'Boolean'
+    };
+
+   case Number:
+    return {
+      value: void 0,
+      type: 'Number'
+    };
+
+   case String:
+    return {
+      value: void 0,
+      type: 'String'
+    };
+
+   default:
+    return {
+      value: value,
+      type: toString.call(value).slice(8, -1)
+    };
+  }
+}, convertType = (any, type) => {
   switch (type) {
    case 'Number':
     return (any => {

package/dist/escape.js

@@ -1,9 +1,13 @@
-const escMap = {
+class UnsafeHtml extends String {}
+
+const unsafeHtml = str => new UnsafeHtml(str), escMap = {
   '&': '&',
   '<': '&lt;',
   '>': '&gt;',
   "'": '&#39;',
   '"': '&quot;'
-}, escHtml = string => ('' + string).replace(/&amp;/g, '&').replace(/[&<>'"]/g, (tag => escMap[tag])), escAttr = string => ('' + string).replace(/['"]/g, (tag => escMap[tag])), esc = (strings, ...vars) => strings.map(((string, i) => string + escHtml(vars[i] ?? ''))).join('');
+}, escHtml = string => string instanceof UnsafeHtml ? string : ('' + string).replace(/&amp;/g, '&').replace(/[&<>'"]/g, (tag => escMap[tag])), esc = (strings, ...vars) => String.raw({
+  raw: strings
+}, ...vars.map(escHtml));
 
-export { esc, escAttr, escHtml };
+export { esc, escHtml, unsafeHtml };

package/dist/index.js

@@ -2,11 +2,11 @@ export { ContextConsumer, ContextProvider, ContextRequestEvent } from './context
 
 export { MiElement, convertType, define } from './element.js';
 
-export { esc, escAttr, escHtml } from './escape.js';
+export { esc, escHtml, unsafeHtml } from './escape.js';
 
 export { refsById, refsBySelector } from './refs.js';
 
-export { default as Signal } from './signal.js';
+export { Computed, default as Signal, State, createSignal, effect } from './signal.js';
 
 export { Store } from './store.js';
 

package/dist/signal.js

@@ -45,9 +45,9 @@ class Computed {
 
 var signal = {
   State: State,
+  Computed: Computed,
   createSignal: createSignal,
-  effect: effect,
-  Computed: Computed
+  effect: effect
 };
 
 export { Computed, State, createSignal, signal as default, effect };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mi-element",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Build lightweight reactive micro web-components",
   "keywords": [],
   "homepage": "https://github.com/commenthol/mi-element/tree/main/packages/mi-element#readme",
@@ -75,22 +75,22 @@
     "types"
   ],
   "devDependencies": {
-    "@eslint/js": "^9.9.1",
+    "@eslint/js": "^9.32.0",
     "@rollup/plugin-terser": "^0.4.4",
-    "@testing-library/dom": "^10.4.0",
-    "@types/node": "^22.5.0",
-    "@vitest/browser": "^2.0.5",
-    "@vitest/coverage-istanbul": "^2.0.5",
-    "eslint": "^9.9.1",
-    "globals": "^15.9.0",
-    "npm-run-all2": "^6.2.2",
-    "playwright": "^1.46.1",
-    "prettier": "^3.3.3",
+    "@testing-library/dom": "^10.4.1",
+    "@types/node": "^22.17.0",
+    "@vitest/browser": "^2.1.9",
+    "@vitest/coverage-istanbul": "^2.1.9",
+    "eslint": "^9.32.0",
+    "globals": "^15.15.0",
+    "npm-run-all2": "^6.2.6",
+    "playwright": "^1.54.2",
+    "prettier": "^3.6.2",
     "rimraf": "^6.0.1",
-    "rollup": "^4.21.1",
-    "typescript": "^5.5.4",
-    "vite": "^5.4.2",
-    "vitest": "^2.0.5"
+    "rollup": "^4.46.2",
+    "typescript": "^5.9.2",
+    "vite": "^5.4.19",
+    "vitest": "^2.1.9"
   },
   "scripts": {
     "all": "npm-run-all pretty lint test build types",
@@ -102,6 +102,7 @@
     "test": "vitest run --coverage",
     "test:browser": "vitest --coverage",
     "dev": "npm run test:browser",
-    "types": "tsc"
+    "types": "tsc",
+    "setup": "pnpm exec playwright install"
   }
 }

package/src/context.js

@@ -64,7 +64,6 @@ export class ContextProvider {
       return
     }
     ev.stopPropagation()
-    console.debug('provider.onContextRequest', this.state)
     let unsubscribe
     if (ev.subscribe) {
       unsubscribe = effect(() => {
@@ -141,7 +140,6 @@ 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

package/src/element.js

@@ -10,17 +10,18 @@ import { createSignal } from './signal.js'
  */
 
 /**
- * class extening HTMLElement to enable deferred rendering on attribute changes
+ * class extending HTMLElement to enable deferred rendering on attribute changes
  * either via `setAttribute(name, value)` or `this[name] = value`.
  * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement
  * @example
  * ```js
  * class Example extends MiElement {
- *  // define all observed attributes with its default value.
+ *  // define all observed attributes with its default initial value.
+ *  // for yet to defined numbers, boolean or strings use `Number`, `Boolean`, `String`
  *  // attributes are accessible via `this[prop]`
  *  // avoid using attributes which are HTMLElement properties e.g. className
  *  static get attributes () {
- *    return { text: 'Hi' }
+ *    return { text: 'Hi', num: Number }
  *  }
  *  render() {
  *    this.renderRoot.innerHTML = `<div></div>`
@@ -43,8 +44,19 @@ import { createSignal } from './signal.js'
  * ```
  */
 export class MiElement extends HTMLElement {
+  /** all attributes are signals! */
   #attr = {}
+  /**
+   * lower-cased or kebab-case attribute names;
+   * Map<lower-cased and kebab-cased attr name, camelCased attr name as string>
+   * @type {Map<string, string>}
+   */
   #attrLc = new Map()
+  /**
+   * initial types (from `static get attributes() { return {} }`)
+   * Map<camelCased attribute name, type as string>
+   * @type {Map<string,string>}
+   */
   #types = new Map()
   #disposers = new Set()
   #controllers = new Set()
@@ -68,17 +80,17 @@ export class MiElement extends HTMLElement {
    */
   #observedAttributes(attributes = {}) {
     for (const [name, value] of Object.entries(attributes)) {
-      this.#types.set(name, initialType(value))
+      const initial = initialValueType(value)
+      this.#types.set(name, initial.type)
       this.#attrLc.set(name.toLowerCase(), name)
       this.#attrLc.set(camelToKebabCase(name), name)
-      this.#attr[name] = createSignal(value)
+      this.#attr[name] = createSignal(initial.value)
       Object.defineProperty(this, name, {
         enumerable: true,
         get() {
           return this.#attr[name].get()
         },
         set(newValue) {
-          console.debug('%s.%s =', this.nodeName, name, newValue)
           const oldValue = this.#attr[name].get()
           if (oldValue === newValue) return
           this.#attr[name].set(newValue)
@@ -146,13 +158,6 @@ export class MiElement extends HTMLElement {
     if (type === 'Boolean' && newValue === 'false') {
       this.removeAttribute(name)
     }
-    console.debug(
-      '%s.attributeChangedCallback("%s",',
-      this.nodeName,
-      name,
-      oldValue,
-      newValue
-    )
     this.requestUpdate()
   }
 
@@ -169,7 +174,6 @@ export class MiElement extends HTMLElement {
       return
     }
     const type = this.#getType(attr)
-    console.debug('%s.setAttribute("%s",', this.nodeName, name, newValue)
 
     // only set string values in these cases
     if (type === 'Boolean') {
@@ -178,7 +182,7 @@ export class MiElement extends HTMLElement {
       } else {
         super.removeAttribute(name)
       }
-    } else if (['String', 'Number'].includes(type) || newValue === true) {
+    } else if (['String', 'Number'].includes(type ?? '') || newValue === true) {
       super.setAttribute(name, newValue)
     } else {
       this.#changedAttr[attr] = this[attr]
@@ -216,7 +220,7 @@ export class MiElement extends HTMLElement {
    */
   addTemplate(template) {
     if (!(template instanceof HTMLTemplateElement)) {
-      console.debug('template is not a HTMLTemplateElement')
+      console.warn('template is not a HTMLTemplateElement')
       return
     }
     this.renderRoot.appendChild(template.content.cloneNode(true))
@@ -327,7 +331,18 @@ const renderTemplate = (element) => {
   element.template = el
 }
 
-const initialType = (value) => toString.call(value).slice(8, -1)
+const initialValueType = (value) => {
+  switch (value) {
+    case Boolean:
+      return { value: undefined, type: 'Boolean' }
+    case Number:
+      return { value: undefined, type: 'Number' }
+    case String:
+      return { value: undefined, type: 'String' }
+    default:
+      return { value, type: toString.call(value).slice(8, -1) }
+  }
+}
 
 const toNumber = (any) => {
   const n = Number(any)

package/src/escape.js

@@ -1,3 +1,13 @@
+class UnsafeHtml extends String {}
+
+/**
+ * tag a string as html for not to be escaped
+ * @param {string} str
+ * @returns {string}
+ */
+// @ts-expect-error
+export const unsafeHtml = (str) => new UnsafeHtml(str)
+
 const escMap = {
   '&': '&',
   '<': '&lt;',
@@ -15,18 +25,12 @@ const escMap = {
  * //> &lt;h1&gt;&quot;One&quot; &amp; &#39;Two&#39; &amp; Works&lt;/h1&gt;
  */
 export const escHtml = (string) =>
-  ('' + string).replace(/&amp;/g, '&').replace(/[&<>'"]/g, (tag) => escMap[tag])
-
-/**
- * escape HTML attribute
- * @param {string} string
- * @returns {string} escaped string
- * @example
- * escapeAttr("One's")
- * //> &quot;One&#39;s&quot;
- */
-export const escAttr = (string) =>
-  ('' + string).replace(/['"]/g, (tag) => escMap[tag])
+  // @ts-expect-error
+  string instanceof UnsafeHtml
+    ? string
+    : ('' + string)
+        .replace(/&amp;/g, '&')
+        .replace(/[&<>'"]/g, (tag) => escMap[tag])
 
 /**
  * template literal to HTML escape all values preventing XSS
@@ -35,4 +39,4 @@ export const escAttr = (string) =>
  * @returns {string}
  */
 export const esc = (strings, ...vars) =>
-  strings.map((string, i) => string + escHtml(vars[i] ?? '')).join('')
+  String.raw({ raw: strings }, ...vars.map(escHtml))

package/src/index.js

@@ -10,14 +10,19 @@ export {
  * @typedef {import('./element.js').HostController} HostController
  */
 export { MiElement, convertType, define } from './element.js'
-export { esc, escAttr, escHtml } from './escape.js'
+export { unsafeHtml, esc, escHtml } from './escape.js'
 export { refsById, refsBySelector } from './refs.js'
 /**
  * @template T
  * @typedef {import('./signal.js').SignalOptions<T>} SignalOptions<T>
  */
-import Signal from './signal.js'
-export { Signal }
+export {
+  default as Signal,
+  State,
+  createSignal,
+  effect,
+  Computed
+} from './signal.js'
 /**
  * @typedef {import('./store.js').Action} Action
  */

package/src/signal.js

@@ -122,4 +122,4 @@ export class Computed {
   }
 }
 
-export default { State, createSignal, effect, Computed }
+export default { State, Computed, createSignal, effect }

package/src/styling.js

@@ -1,7 +1,7 @@
 import { camelToKebabCase } from './case.js'
 
 /**
- * Construct className based on trueish values of map
+ * Construct className based on true-ish values of map
  * @param {{[name: string]: string | boolean | number}} map
  * @returns {string}
  */
@@ -31,3 +31,45 @@ export const styleMap = (map, options) => {
   }
   return acc.join(';')
 }
+
+// ----
+
+let globalSheets = null
+/**
+ * obtain and cache global stylesheets
+ * @returns {CSSStyleSheet[]}
+ */
+function getGlobalStyleSheets() {
+  if (globalSheets === null) {
+    globalSheets = Array.from(document.styleSheets).map(({ cssRules }) => {
+      const sheet = new CSSStyleSheet()
+      const css = Array.from(cssRules)
+        .map((rule) => rule.cssText)
+        .join(' ')
+      sheet.replaceSync(css)
+      return sheet
+    })
+  }
+  return globalSheets
+}
+
+/**
+ * apply global style sheets to shadowRoot
+ * @param {ShadowRoot} renderRoot
+ * @example
+ * class MyComponent extends MiElement {
+ *  render() {
+ *    addGlobalStyles(this.renderRoot)
+ *  }
+ * }
+ */
+export function addGlobalStyles(renderRoot) {
+  renderRoot.adoptedStyleSheets.push(...getGlobalStyleSheets())
+}
+
+/**
+ * Helper literal to show css styles in JS e.g. with
+ * https://marketplace.visualstudio.com/items?itemName=Tobermory.es6-string-html
+ */
+export const css = (strings, ...values) =>
+  String.raw({ raw: strings }, ...values)

package/types/context.d.ts

@@ -33,7 +33,7 @@ export class ContextRequestEvent extends Event {
      * @param {(value: any, unsubscribe?: () => void) => void} callback
      * @param {boolean} [subscribe=false] subscribe to value changes
      */
-    constructor(context: Context, callback: (value: any, unsubscribe?: () => void) => void, subscribe?: boolean | undefined);
+    constructor(context: Context, callback: (value: any, unsubscribe?: () => void) => void, subscribe?: boolean);
     context: Context;
     callback: (value: any, unsubscribe?: () => void) => void;
     subscribe: boolean | undefined;
@@ -52,7 +52,7 @@ export class ContextConsumer implements HostController {
     constructor(host: HTMLElement, context: Context, options?: {
         subscribe?: boolean | undefined;
         validate?: ((any: any) => boolean) | undefined;
-    } | undefined);
+    });
     host: HTMLElement;
     context: Context;
     subscribe: boolean;

package/types/element.d.ts

@@ -6,17 +6,18 @@
  * removed from the DOM, usually with disconnectedCallback()
  */
 /**
- * class extening HTMLElement to enable deferred rendering on attribute changes
+ * class extending HTMLElement to enable deferred rendering on attribute changes
  * either via `setAttribute(name, value)` or `this[name] = value`.
  * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement
  * @example
  * ```js
  * class Example extends MiElement {
- *  // define all observed attributes with its default value.
+ *  // define all observed attributes with its default initial value.
+ *  // for yet to defined numbers, boolean or strings use `Number`, `Boolean`, `String`
  *  // attributes are accessible via `this[prop]`
  *  // avoid using attributes which are HTMLElement properties e.g. className
  *  static get attributes () {
- *    return { text: 'Hi' }
+ *    return { text: 'Hi', num: Number }
  *  }
  *  render() {
  *    this.renderRoot.innerHTML = `<div></div>`
@@ -75,7 +76,7 @@ export class MiElement extends HTMLElement {
      * @param {Record<string,any>} [_changedAttributes] previous values of changed attributes
      * @returns {boolean}
      */
-    shouldUpdate(_changedAttributes?: Record<string, any> | undefined): boolean;
+    shouldUpdate(_changedAttributes?: Record<string, any>): boolean;
     /**
      * request rendering
      */
@@ -94,7 +95,7 @@ export class MiElement extends HTMLElement {
      * @param {Record<string,any>} [_changedAttributes] previous values of changed
      * attributes
      */
-    update(_changedAttributes?: Record<string, any> | undefined): void;
+    update(_changedAttributes?: Record<string, any>): void;
     /**
      * Adds listener function for eventName. listener is removed before component
      * disconnects
@@ -102,7 +103,7 @@ export class MiElement extends HTMLElement {
      * @param {EventListenerOrEventListenerObject} listener
      * @param {Node|Document|Window} [node=this]
      */
-    on(eventName: string, listener: EventListenerOrEventListenerObject, node?: Node | Document | Window | undefined): void;
+    on(eventName: string, listener: EventListenerOrEventListenerObject, node?: Node | Document | Window): void;
     /**
      * Adds one-time listener function for eventName. The next time eventName is
      * triggered, this listener is removed and then invoked.

package/types/escape.d.ts

@@ -1,3 +1,3 @@
+export function unsafeHtml(str: string): string;
 export function escHtml(string: string): string;
-export function escAttr(string: string): string;
 export function esc(strings: string[], ...vars: any[]): string;

package/types/index.d.ts

@@ -1,4 +1,3 @@
-export { Signal };
 export { Store } from "./store.js";
 export type Context = import("./context.js").Context;
 export type HostController = import("./element.js").HostController;
@@ -7,9 +6,9 @@ export type HostController = import("./element.js").HostController;
  */
 export type SignalOptions<T> = import("./signal.js").SignalOptions<T>;
 export type Action = import("./store.js").Action;
-import Signal from './signal.js';
 export { ContextConsumer, ContextProvider, ContextRequestEvent } from "./context.js";
 export { MiElement, convertType, define } from "./element.js";
-export { esc, escAttr, escHtml } from "./escape.js";
+export { unsafeHtml, esc, escHtml } from "./escape.js";
 export { refsById, refsBySelector } from "./refs.js";
+export { default as Signal, State, createSignal, effect, Computed } from "./signal.js";
 export { classMap, styleMap } from "./styling.js";

package/types/signal.d.ts

@@ -23,7 +23,7 @@ export class State<T> extends EventTarget {
      * @param {T|null} [value]
      * @param {SignalOptions<T>} [options]
      */
-    constructor(value?: T | null | undefined, options?: SignalOptions<T> | undefined);
+    constructor(value?: T | null, options?: SignalOptions<T>);
     /**
      * @returns {T|null|undefined}
      */
@@ -34,7 +34,7 @@ export class State<T> extends EventTarget {
     set(nextValue: T | null | undefined): void;
     #private;
 }
-export function createSignal<T>(initialValue: T, options?: SignalOptions<T> | undefined): State<T>;
+export function createSignal<T>(initialValue: T, options?: SignalOptions<T>): State<T>;
 /**
  * @template T
  */
@@ -52,9 +52,9 @@ export class Computed<T> {
 }
 declare namespace _default {
     export { State };
+    export { Computed };
     export { createSignal };
     export { effect };
-    export { Computed };
 }
 export default _default;
 /**

package/types/store.d.ts

@@ -53,7 +53,7 @@ export class Store<T> extends State<any> {
      * const store = new Store(actions, initialValue, options)
      * ```
      */
-    constructor(actions: Record<string, Action>, initialValue?: T | null | undefined, options?: SignalOptions<T> | undefined);
+    constructor(actions: Record<string, Action>, initialValue?: T | null, options?: SignalOptions<T>);
 }
 export type MiElement = import("./element.js").MiElement;
 export type Action = (state: any, data?: any) => any;

package/types/styling.d.ts

@@ -1,3 +1,14 @@
+/**
+ * apply global style sheets to shadowRoot
+ * @param {ShadowRoot} renderRoot
+ * @example
+ * class MyComponent extends MiElement {
+ *  render() {
+ *    addGlobalStyles(this.renderRoot)
+ *  }
+ * }
+ */
+export function addGlobalStyles(renderRoot: ShadowRoot): void;
 export function classMap(map: {
     [name: string]: string | boolean | number;
 }): string;
@@ -5,4 +16,5 @@ export function styleMap(map: {
     [name: string]: string | number | undefined | null;
 }, options?: {
     unit?: string | undefined;
-} | undefined): string;
+}): string;
+export function css(strings: any, ...values: any[]): string;