mi-element 0.6.0 → 0.6.1

package/docs/store.md

@@ -0,0 +1,65 @@
+# Store
+
+Store implements [Flux](https://www.npmjs.com/package/flux) pattern, which is a
+signal triggered by an action (dispatchers).
+
+1. Define actions which allow changing the store value.  
+   The actions must be a function with the shape:
+
+   ```js
+   const actions = {
+     [actionName]: (change) => (state) => {
+       // change state based on change e.g.
+       const stateChange = { ...state, change }
+       return stateChange
+     }
+   }
+   ```
+
+2. Create store and add export to component.  
+   Component imports store and connects to it by subscribing with a callback
+   function to receive any state changes:
+   ```js
+   const callback = (state) => {
+     // update component with new state
+   }
+   ```
+
+Sample:
+
+```js
+import { Store, Signal } from 'mi-element'
+
+const actions = {
+  increment:
+    (by = 1) =>
+    (state) =>
+      state + by
+}
+const initialValue = 1
+const store = new Store(actions, initialValue)
+
+// create effect, which is executed immediately
+const unsubscribe = Signal.effect(() => console.log(`count is ${store.get()}`))
+//> count is 1
+
+// change the store
+store.increment(2) // increment by 2
+//> count is 3
+
+unsubscribe()
+```
+
+If `initialValue` is an object, the object's reference must be changed
+with the spread operator to notify on state changes, e.g.
+
+**Example**
+
+```js
+const initialValue = { count: 0, other: 'foo' }
+const actions = {
+  increment:
+    (by = 1) =>
+    (state) => ({ ...state, count: state.count + by })
+}
+```

package/docs/styling.md

@@ -0,0 +1,77 @@
+**Table of contents**
+
+<!-- !toc (minlevel=2) -->
+
+- [classMap](#classmap)
+- [styleMap](#stylemap)
+- [addGlobalStyles](#addglobalstyles)
+
+<!-- toc! -->
+
+# Styling
+
+## classMap
+
+Obtain a class string from an object. Only class-names with trueish values are
+returned.
+
+```js
+import { classMap } from 'mi-element'
+
+const className = classMap({ enabled: true, hidden: '', number: 1 })
+//> className == 'enabled number'
+```
+
+## styleMap
+
+Convert a map of styles into a styles string. CamelCased properties are
+converted to kebab-case. Numbers are converted to css `px` unit. This can be
+changed through its options.
+
+```js
+import { styleMap } from 'mi-element'
+
+const styles = styleMap(
+  { backgroundColor: 'blue', color: '#fff', width: 200 },
+  { unit: 'px' } // optional
+)
+//> styles == 'background-color:blue;color:#fff;width:200px'
+```
+
+Signature
+
+```ts
+function styleMap(
+  map: { [name: string]: string | number | undefined | null },
+  options?: { unit?: string | undefined } | undefined
+): string
+```
+
+## addGlobalStyles
+
+Apply global style sheets to shadowRoot of a web-component.
+
+E.g. you'd like to apply your global style sheet to
+
+```css
+h1 { color: rebeccapurple; }
+```
+
+```js
+import { addGlobalStyles } from 'mi-element'
+
+const template = document.createElement('template')
+template.innerHTML = `<h1>Hello World!</h1>`
+
+customElements.define(
+  'x-hello-world',
+  class extends HTMLElement {
+    connectedCallback() {
+      this.renderRoot = this.shadowRoot ?? this.attachShadow({ mode: 'open' })
+      // apply global styles
+      addGlobalStyles(this.renderRoot)
+      this.renderRoot.append(template.content.cloneNode(true))
+    }
+  }
+)
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mi-element",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Build lightweight reactive micro web-components",
   "keywords": [],
   "homepage": "https://github.com/commenthol/mi-element/tree/main/packages/mi-element#readme",
@@ -70,10 +70,11 @@
   "files": [
     "src",
     "dist",
+    "docs",
     "types"
   ],
   "dependencies": {
-    "mi-signal": "0.6.0"
+    "mi-signal": "0.6.1"
   },
   "devDependencies": {
     "@eslint/js": "^9.33.0",
@@ -89,11 +90,11 @@
     "playwright": "^1.54.2",
     "prettier": "^3.6.2",
     "rimraf": "^6.0.1",
-    "rollup": "^4.46.2",
+    "rollup": "^4.46.3",
     "typescript": "^5.9.2",
     "vite": "^7.1.2",
     "vitest": "^3.2.4",
-    "mi-html": "0.6.0"
+    "mi-html": "0.6.1"
   },
   "scripts": {
     "all": "npm-run-all pretty lint test build types",

package/src/element.js

@@ -66,6 +66,7 @@ export class MiElement extends HTMLElement {
    * Default options used when calling `attachShadow`. Used in
    * `connectedCallback()`.
    * If override is `null`, no shadow-root will be attached.
+   * @type {{mode: string}|null}
    */
   static shadowRootOptions = { mode: 'open' }
 
@@ -75,20 +76,20 @@ export class MiElement extends HTMLElement {
    */
   static template
 
-  // /**
-  //  * observable attributes
-  //  * @returns {Record<string, any>|{}}
-  //  */
-  // static get attributes() {
-  //   return {}
-  // }
-  // /**
-  //  * observable properties
-  //  * @returns {Record<string, any>|{}}
-  //  */
-  // static get properties() {
-  //   return {}
-  // }
+  /**
+   * observable attributes
+   * @returns {Record<string, any>|{}}
+   */
+  static get attributes() {
+    return {}
+  }
+  /**
+   * observable properties
+   * @returns {Record<string, any>|{}}
+   */
+  static get properties() {
+    return {}
+  }
 
   constructor() {
     super()

package/types/element.d.ts

@@ -44,15 +44,26 @@ export class MiElement extends HTMLElement {
      * Default options used when calling `attachShadow`. Used in
      * `connectedCallback()`.
      * If override is `null`, no shadow-root will be attached.
+     * @type {{mode: string}|null}
      */
     static shadowRootOptions: {
         mode: string;
-    };
+    } | null;
     /**
      * defines template for render().
      * @type {String|HTMLTemplateElement}
      */
     static template: string | HTMLTemplateElement;
+    /**
+     * observable attributes
+     * @returns {Record<string, any>|{}}
+     */
+    static get attributes(): Record<string, any> | {};
+    /**
+     * observable properties
+     * @returns {Record<string, any>|{}}
+     */
+    static get properties(): Record<string, any> | {};
     /**
      * creates the element's renderRoot, sets up styling
      * @category lifecycle