npm - mi-element - Versions diffs - 0.6.0 → 0.6.1 - Mend

mi-element 0.6.0 → 0.6.1

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 (17) hide show

package/docs/controller.md ADDED Viewed

@@ -0,0 +1,82 @@
+# Controllers
+A controller is meant to hook into the components update lifecycle and provide
+an updated value to the host component.
+```js
+/**
+ * @file './my-clock.js'
+ * Defines custom element my-clock with controller
+ */
+import { define, MiElement } from 'mi-element'
+class ClockController {
+  /**
+   * @param {MiElement} host
+   */
+  constructor(host) {
+    this.host = host
+    // Add controller to component.
+    this.host.addController(this)
+    // As soon as component is mounted `hostConnected()` is called.
+  }
+  /**
+   * called by the hosts connectedCallback()
+   */
+  hostConnected() {
+    this._interval() // start timer
+  }
+  /**
+   * called by the hosts disconnectedCallback(); do cleanup herein.
+   */
+  hostDisconnected() {
+    clearTimeout(this._timerId)
+  }
+  /**
+   * periodically update controller value
+   */
+  _interval() {
+    this.value = new Date()
+    // on every change call requestUpdate()
+    this.host.requestUpdate()
+    this._timerId = setTimeout(() => {
+      this._interval()
+    }, 1000)
+  }
+}
+define(
+  'my-clock',
+  class extends MiElement {
+    constructor() {
+      super()
+      // create controller and pass `this` as host
+      this.controller = new ClockController(this)
+    }
+    update() {
+      // get value from controller
+      const { value } = this.controller
+      // apply some formatting
+      const formattedDateTime = new Intl.DateTimeFormat(navigator.language, {
+        dateStyle: 'short',
+        timeStyle: 'long'
+      }).format(value)
+      // update component
+      this.renderRoot.textContent = formattedDateTime
+    }
+  }
+)
+```
+```html
+<!-- @file ./index.html -->
+<!doctype html>
+<html>
+  <body>
+    <my-clock></my-clock>
+    <script type="module" src="./my-clock.js"></script>
+  </body>
+</html>
+```

package/docs/element.md ADDED Viewed

@@ -0,0 +1,394 @@
+**Table of contents**
+<!-- !toc (minlevel=2) -->
+* [constructor()](#constructor)
+* [connectedCallback()](#connectedcallback)
+* [disconnectedCallback()](#disconnectedcallback)
+* [attributeChangedCallback(name, oldValue, newValue)](#attributechangedcallbackname-oldvalue-newvalue)
+* [Update Cycle](#update-cycle)
+* [render()](#render)
+* [update(changedAttributes)](#updatechangedattributes)
+* [shouldUpdate(changedAttributes)](#shouldupdatechangedattributes)
+* [on(eventName, listener, \[node\])](#oneventname-listener-node)
+* [once(eventName, listener, \[node\])](#onceeventname-listener-node)
+<!-- toc! -->
+# Element Lifecycle
+MiElement components use the [standard custom element lifecycle callbacks][].
+[standard custom element lifecycle callbacks]: https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements#custom_element_lifecycle_callbacks
+## constructor()
+Called whenever a new element is created. Default attributes are being applied
+from the `static attributes` object. From there setters and getters for property
+changes using `.[name] = newValue` instead of `setAttribute(name, newValue)` are
+applied.
+Direct properties can also made observable with `static properties` as long as
+not yet being defined within attributes.
+```js
+class extends MiElement {
+  /**
+   * Declare observable attributes and their default values with this getter.
+   * Do not use `static attribute = { text: 'Hi' }` as components attributes
+   * will use a shallow copy only. With the getter we always get a real "deep"
+   * copy.
+   *
+   * For yet to defined numbers, boolean or strings use `Number`, `Boolean`,
+   * `String`. Attributes are accessible via `.[name]` or `.getAttribute(name)`.
+   * Avoid using attributes which are HTMLElement properties e.g. `className`.
+   */
+  static get attributes () {
+    return {
+      text: 'Hi',
+      // A yet to be defined boolean value
+      focus: Boolean
+    }
+  }
+  /**
+   * Declare observable properties and their default values.
+   * Any changed value of a property, using `.[name] = nextValue` assignment,
+   * will cause a rerender.
+   * In case of objects or arrays consider changing the reference with the
+   * spread operator like `{...obj}` or `[...arr]` creating a new reference.
+   * If name is already declared in `attributes` it will be ignored.
+   */
+  static get properties () {
+    return { prop: 0 }
+  }
+  constructor() {
+    super()
+    // optionally declare "non observable" and internal properties
+    this.foo = 'foo'
+  }
+}
+```
+## connectedCallback()
+Invoked when a component is being added to the document's DOM.
+Micro components create `this.renderRoot` (typically same as `this.shadowRoot`
+for open components) using `this.attachShadow(shadowRootOptions)`. Shadow root
+options are taken from the components `static shadowRootOptions = { mode: 'open'
+}`. In advanced cases where no shadow root is desired, set `static
+shadowRootOptions = null`
+The most common use case is adding event listeners to external nodes in
+`connectedCallback()`. Typically, anything done in `connectedCallback()` should
+be undone when the element is disconnected, like removing all event listeners on
+external nodes to prevent memory leaks.
+Then the first `render()` is issued with a `requestUpdate()`
+```js
+class extends MiElement {
+  // { mode: 'open' } is the default shadow root option
+  // use `null` for no shadow root or { mode: 'closed' } for closed mode
+  static shadowRootOptions = { mode: 'open' }
+  connectedCallback() {
+    super.connectedCallback() // don't forget to call the super method
+    window.addEventListener('keydown', this._handleKeyDown)
+  }
+  // create a event listener which is bound to this component
+  // note the `_listener () => {}` syntax (instead of `_listener () {}`)
+  _handleKeyDown = (ev) => {
+    // do sth. with the event
+  }
+  disconnectedCallback() {
+    super.disconnectedCallback()
+    window.removeEventListener('keydown', this._handleKeyDown)
+  }
+}
+```
+To simplify further use `this.on()` which automatically removes the event listener
+on `window` when the component is unmounted with `disconnectedCallback()`.
+```js
+class extends MiElement {
+  connectedCallback() {
+    super.connectedCallback()
+    this.on('keydown', this._handleKeyDown, window)
+  }
+  // create a event listener which is bound to this component
+  // note the `_listener () => {}` syntax (instead of `_listener () {}`)
+  _handleKeyDown = (ev) => {
+    // do sth. with the event
+  }
+}
+```
+## disconnectedCallback()
+Invoked when a component is removed from the document's DOM.
+Typically, anything done in `connectedCallback()` should be undone when the
+element is disconnected, like removing all event listeners on external nodes to
+prevent memory leaks.
+See previous example.
+!!! INFO No need to remove internal event listeners
+    You don't need to remove event listeners added on the component's own
+    DOM. This includes those added in your template. Unlike external
+    event listeners, these will be garbage collected with the component.
+## attributeChangedCallback(name, oldValue, newValue)
+Invoked when one of the element’s observedAttributes changes.
+Usually no need to do something here. But if, don't forget to call
+`super.attributeChangedCallback(name, oldValue, newValue)` within.
+## Update Cycle
+```mermaid
+flowchart TD
+  constructoR("constructor()")
+  connectedCallback("connectedCallback()")
+  disconnectedCallback("disconnectedCallback()")
+  render("render()")
+  requestUpdate("requestUpdate()")
+  shouldUpdate("shouldUpdate(changedAttributes)")
+  update("update(changedAttributes)")
+  setAttribute("setAttribute(name, newVale)")
+  setProperty(".[name] = newValue")
+  START --> constructoR
+  constructoR -.->|"mount to DOM"| connectedCallback
+  connectedCallback --> render
+  render --> requestUpdate
+  requestUpdate -.->|async| shouldUpdate
+  shouldUpdate -->|true| update
+  setAttribute -->|"attributeChangedCallback"| requestUpdate
+  setProperty --> requestUpdate
+  update -.->|change| setAttribute
+  update -.->|change| setProperty
+  connectedCallback -.->|"unmount from DOM"| disconnectedCallback
+  disconnectedCallback --> END
+```
+A micro component usually implements `render()` and `update()`:
+```js
+import { define, MiElement, refsBySelector } from 'mi-element'
+class Counter extends MiElement {
+  static get attributes() {
+    return { value: 0 }
+  }
+  // define the innerHTML template for the component
+  static template = `
+  <button>Count</button>
+  <p>Counter value: <span>0</span></p>
+  `
+  render() {
+    // If `static template` is provided, it has already been rendered
+    // on `this.renderRoot`
+    // obtain references for events and update() with `refsBySelector`
+    this.refs = refsBySelector(this.renderRoot, {
+      button: 'button',
+      count: 'span'
+    })
+    // apply event listener on button
+    this.refs.button.addEventListener('click', () => {
+      // observed attribute will trigger `requestUpdate()` which then async
+      // calls `update()`
+      this.value++
+    })
+  }
+  update() {
+    this.refs.count.textContent = this.value
+  }
+}
+```
+## render()
+Initial rendering of the component. Try to render the component only once!
+If you need re-rendering by recrating the DOM do this outside of `render()`
+Within the `render()` method, bear in mind to:
+- Avoid changing the component's state.
+- Avoid producing any side effects.
+- Use only the component's attributes as input.
+!!! WARNING XSS - Cross-Site Scripting
+    Using [`innerHTML`][innerHTML] to create the components DOM is susceptible to
+    [XSS][XSS] attacks in case that user-supplied data contains valid HTML markup.
+In all other cases you may consider the <code>esc``</code> template literal or
+`escHtml()` from the "mi-element" import, which escapes user-supplied data.
+[innerHTML]: https://developer.mozilla.org/en-US/docs/Web/API/Element/innerHTML
+[XSS]: https://en.wikipedia.org/wiki/Cross-site_scripting
+```js
+import { define, MiElement } from 'mi-element'
+// (1) get template directly from html ...
+const template = document.querySelector('template#counter')
+// (2) or define outside the component ...
+const template = document.createElement('template')
+template.innerHTML = `
+<button>Count</button>
+<p>Counter value: <span>0</span></p>
+`
+class Counter extends MiElement {
+  // (3) or as static string on the component (needs define from 'mi-element')
+  static template = `
+  <button id>Count</button>
+  <p>Counter value: <span id="count">0</span></p>
+  `
+  // ...
+  render() {
+    /*
+    // NEVER DO THIS, as this may cause XSS ///
+    this.renderRoot.innerHTML = `
+      <button>Count</button>
+      <p>Counter value: <span>${this.count}</span></p>`
+    */
+    // always render a cloned template, which is safe
+    // NOT NEEDED with option (3) `static template = '...'`
+    this.addTemplate(template)
+  }
+}
+// always use define with (3)
+define('mi-element-counter', Counter)
+```
+To more easily obtain any references of interest use the `refs()` helper by
+adding `id` attributes to the nodes where updates shall happen or event
+listeners must be applied.
+```js
+import { MiElement, define, refsById } from 'mi-element'
+class Counter extends MiElement {
+  static template = `
+  <button id>Count</button>
+  <p>Counter value: <span id="count">0</span></p>
+  `
+  render() {
+    // template is already rendered on `this.renderRoot`
+    // get refs though `refsById` of `refsBySelector`
+    this.refs = refsById(this.renderRoot)
+    // this.refs == {button: <button>, count: <span>}
+  }
+}
+define('mi-element-counter', Counter)
+```
+## update(changedAttributes)
+Here all content or render updates on the component should happen. Avoid
+re-rendering the full component and only apply partial changes on the
+rendered elements as much as possible.
+```js
+class Counter extends MiElement {
+  // ...
+  update() {
+    this.refs.count.textContent = this.value
+  }
+}
+```
+In order to allow judged decisions on the area where an update should take place
+any changed attributes are passed.
+To mitigate [XSS][] attacks prefer the use of `.textContent` and avoid
+~~`.innerHTML`~~. For attribute changes use `.setAttribute(name, newValue)`.
+Both `.textContent` and `setAttribute()` provide escaping for you.
+For finer control on updates the use of signals is encouraged. With this there
+is no need to add logic to `shouldUpdate()` or `update()`.
+```js
+import { MiElement, Signal } from 'mi-element'
+class Counter extends MiElement {
+  static get attributes() {
+    return { value: 0 }
+  }
+  static template = `
+  <button>Count</button>
+  <p>Counter value: <span>0</span></p>
+  `
+  render() {
+    const refs = refsBySelector(this.renderRoot, {
+      button: 'button',
+      count: 'span'
+    })
+    refs.button.addEventListener('click', () => {
+      this.value++
+    })
+    Signal.effect(() => {
+      // an update only happens if `this.value` changes;
+      // other attribute changes are ignored.
+      refs.count.textContent = this.value
+    })
+  }
+}
+```
+## shouldUpdate(changedAttributes)
+Convenience method in order to be able to decide on the changed attributes,
+whether `update()` should be called or not.
+Return `true` if component should be updated.
+## on(eventName, listener, \[node\])
+Adds listener function for eventName. listener is removed before component
+disconnects.
+```js
+class Router extends MiElement {
+  render() {
+    // add event listener 'hashchange' to `window` which is disposed as soon as
+    // the component unmounts
+    this.on('hashchange', this.update, window)
+  }
+  // ...
+}
+```
+## once(eventName, listener, \[node\])
+Adds one-time listener function for eventName. The next time eventName is
+triggered, this listener is removed and then invoked.

package/docs/reactivity.md ADDED Viewed

@@ -0,0 +1,41 @@
+# Reactivity with mi-html
+MiElement can be used with [mi-html][] for reactive updates.
+To install use
+    pnpm install mi-html
+MiElement provides signals for all its attributes defined in `static get
+attributes() {}`.
+```js
+import { define, MiElement } from 'mi-element'
+import { html, render } from 'mi-html'
+define(
+  'mi-counter',
+  class extends MiElement {
+    static get attributes() {
+      return {
+        count: 1 //<< this.count is already a signal
+      }
+    }
+    render() {
+      render(
+        this.renderRoot,
+        // use callback function!
+        () =>
+          html`<button @click=${() => this.count++}>
+            Clicked ${this.count} times
+          </button> `
+      )
+    }
+  }
+)
+```
+See `./example/mi-html/index.html` for a running sample.
+[mi-html]: https://github.com/commenthol/mi-element/blob/main/packages/mi-html/README.md

package/docs/signal.md ADDED Viewed

@@ -0,0 +1,192 @@
+**Table of contents**
+<!-- !toc (minlevel=2) -->
+* [State, createSignal](#state-createsignal)
+* [effect](#effect)
+  * [DONT'S](#donts)
+* [Computed Signals](#computed-signals)
+* [Signals in MiElement](#signals-in-mielement)
+<!-- toc! -->
+# Signal
+Signal is the core for any reactive behavior of mi-element.
+It loosely follows the [TC39 JavaScript Signals standard proposal][].
+## State, createSignal
+Reactive state and its subscribers is managed in this class. With
+`.set(nextValue)` and `.get()` access to the state is achieved.
+For convenience there is a `createSignal(initialValue<T>): State<T>` function to
+create a signal.
+```js
+import { createSignal, State } from 'mi-element'
+const signal = createSignal(1)
+// same as
+const signal = new State(1)
+signal.get()
+//> 1
+signal.set(4)
+signal.get()
+//> 4
+```
+For controlling the notifications to subscribers, the signal option `equals` for
+a custom comparison function can be used, e.g. to trigger an effect on every
+`.set(nextValue)`
+```js
+// default is:
+const equals = (value, nextValue) => value === nextValue
+// changes to trigger change on every `.set()`
+const equals = (value, nextValue) => true
+const signal = createSignal(initialValue, { equals })
+```
+## effect
+Reactivity is achieved by subscribing to a signals State using an effect
+callback function. Such callback function is called for registration to the
+signals state as well as to update on any change through
+`signal.set(nextValue)`. Within that callback the `signal.get()` must be called
+_synchronously_!
+```js
+import { createSignal, effect } from 'mi-element'
+const signal = createSignal(1)
+const callback = () => console.log('value is %s', signal.get())
+// `callback` is executed with assigning to the effect!
+const unsubscribe = effect(callback)
+//> "value is 1"
+signal.set(4)
+//> "value is 4"
+// Signal.effect returns a function to unsubscribe `callback` from the signal
+unsubscribe()
+signal.set(5)
+// gives no console.log output
+```
+For asynchronous usage, request the value from the signal first. Otherwise no
+subscription to the signal will take place.
+```js
+const signal = createSignal(1)
+const callback = async () => {
+  // synchronously get the value
+  const value = signal.get()
+  const p = Promise.withResolvers()
+  setTimeout(() => {
+    console.log('value is %s', )
+    p.resolve()
+  }, 100)
+}.catch(() => {})
+// callback is executed with assigning to the effect!
+effect(callback)
+```
+### DONT'S
+Effects are executed synchronously for a better debugging experience. But be
+warned to never set the signal in the an effects callback!
+```js
+const signal = createSignal(0)
+// DON'T DO THIS
+effect(() => {
+  const value = signal.get()
+  signal.set(value++) //< meeeeh
+})
+```
+The signal value getter triggers the registration of the callback through the
+effect. So don't hide a signals getter inside conditionals!
+```js
+const signal = createSignal(0)
+const rand = Math.random()
+// DON'T DO THIS
+effect(() => {
+  if (rand < 0.5) {
+    console.log(signal.get()) //< meeeeh
+  }
+})
+// DO THIS
+effect(() => {
+  const value = signal.get() //< much better
+  if (rand < 0.5) {
+    console.log(value)
+  }
+})
+```
+## Computed Signals
+Computed signals from more than one signal can be obtained from `Computed`.
+```js
+const firstName = createSignal('Joe')
+const lastName = createSignal('Doe')
+// define computed signal
+const name = new Computed(() => `${firstName.get()} ${lastName.get()}`)
+const events = []
+// apply effect
+effect(() => console.log(name.get()))
+//> 'Joe Doe'
+firstName.set('Alice')
+//> 'Alice Doe'
+lastName.set('Wonderland')
+//> 'Alice Wonderland'
+```
+## Signals in MiElement
+MiElement attributes are backed by signals. To subscribe to reactive changes a
+`Signal.effect` callback can be used on all observed attributes.
+```js
+import { effect, define, MiElement, refByIds } from 'mi-element'
+define(
+  'mi-counter',
+  class extends MiElement {
+    static template = `
+      <button id> + </button>
+      <div id></div>
+    `
+    static get attributes() {
+      return {
+        // define reactive attribute
+        count: 0
+      }
+    }
+    render() {
+      this.refs = refsById(this.renderRoot)
+      this.refs.button.addEventListener('click', () => {
+        // change observed and reactive attribute...
+        this.count++
+      })
+      effect(() => {
+        // ...triggers update on every change
+        this.refs.div.textContent = `${this.count} clicks counted`
+      })
+    }
+  }
+)
+```
+[TC39 JavaScript Signals standard proposal]: https://github.com/tc39/proposal-signals