mi-element 0.0.1 → 0.1.0

package/src/element.js

@@ -0,0 +1,342 @@
+/**
+ * @typedef {object} HostController controller
+ * @property {() => void} hostConnected is called when host element is added to
+ * the DOM, usually with connectedCallback()
+ * @property {() => void} hostDisconnected is called when host element is
+ * removed from the DOM, usually with disconnectedCallback()
+ */
+
+/**
+ * class extening 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.
+ *  // attributes are accessible via `this[prop]`
+ *  // avoid using attributes which are HTMLElement properties e.g. className
+ *  static get attributes () {
+ *    return { text: 'Hi' }
+ *  }
+ *  render() {
+ *    this.renderRoot.innerHTML = `<div></div>`
+ *    this.refs = {
+ *      div: this.renderRoot.querySelector('div')
+ *    }
+ *  }
+ *  // render method called every time an attribute changes
+ *  update() {
+ *    this.refs.div.textContent = this.text
+ *  }
+ * }
+ * // create a custom element with the `define` function (see below)
+ * define('x-example', Example)
+ * // create a DOM node and re-render via attribute or property changes
+ * const elem = document.createElement('x-example')
+ * elem.setAttribute('text', 'set attribute')
+ * // or if change is triggered by property
+ * elem.text = 'set property'
+ * ```
+ */
+export class MiElement extends HTMLElement {
+  #attr = {}
+  #attrLc = new Map()
+  #types = new Map()
+  #disposers = new Set()
+  #controllers = new Set()
+  #changedAttr = {}
+
+  /**
+   * Default options used when calling `attachShadow`. Used in
+   * `connectedCallback()`.
+   * If override is `null`, no shadow-root will be attached.
+   */
+  static shadowRootOptions = { mode: 'open' }
+
+  constructor() {
+    super()
+    // @ts-expect-error
+    this.#attr = { ...this.constructor.attributes }
+    this.#observedAttributes()
+  }
+
+  /**
+   * requests update on component when property changes
+   */
+  #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, {
+        enumerable: true,
+        get() {
+          return this.#attr[name]
+        },
+        set(newValue) {
+          console.debug('%s.%s =', this.nodeName, name, newValue)
+          const oldValue = this.#attr[name]
+          if (oldValue === newValue) return
+          this.#attr[name] = newValue
+          this.#changedAttr[name] = newValue
+          this.requestUpdate()
+        }
+      })
+    }
+  }
+
+  /**
+   * return camelCased value instead of possible lowercased
+   * @param {string} name
+   * @returns
+   */
+  #getName(name) {
+    return this.#attrLc.get(name) || name
+  }
+
+  #getType(name) {
+    return this.#types.get(name)
+  }
+
+  /**
+   * creates the element's renderRoot, sets up styling
+   * @category lifecycle
+   */
+  connectedCallback() {
+    this.#controllers.forEach((controller) => controller.hostConnected?.())
+    // create render root
+    // @ts-expect-error
+    const { shadowRootOptions, template } = this.constructor
+    this.renderRoot = shadowRootOptions
+      ? (this.shadowRoot ?? this.attachShadow(shadowRootOptions))
+      : this
+    this.addTemplate(template)
+    // trigger initial rendering such that children can be added via JS
+    this.render()
+    // and update
+    this.requestUpdate()
+  }
+
+  /**
+   * unsubscribe from all events and disconnect controllers
+   */
+  disconnectedCallback() {
+    // unsubscribe from all subscriptions
+    this.#disposers.forEach((remover) => remover())
+    // disconnect all controllers
+    this.#controllers.forEach((controller) => controller.hostDisconnected?.())
+  }
+
+  /**
+   * @param {string} name change attribute
+   * @param {any} _oldValue
+   * @param {any} newValue new value
+   */
+  attributeChangedCallback(name, _oldValue, newValue) {
+    const attr = this.#getName(name)
+    const type = this.#getType(attr)
+    const _newValue = convertType(newValue, type)
+    this.#attr[attr] = this.#changedAttr[attr] = _newValue
+    // correct initial setting of `trueish="false"` otherwise there's no chance
+    // to overwrite a trueish value. The case `falsish="true"` is covered.
+    if (type === 'Boolean' && newValue === 'false') {
+      this.removeAttribute(name)
+    }
+    console.debug(
+      '%s.attributeChangedCallback("%s",',
+      this.nodeName,
+      name,
+      _oldValue,
+      newValue
+    )
+    this.requestUpdate()
+  }
+
+  /**
+   * Set string and number attributes on element only. Set all other values as
+   * properties to avoid type conversion to and from string
+   * @param {string} name
+   * @param {any} newValue
+   */
+  setAttribute(name, newValue) {
+    const attr = this.#getName(name)
+    // only allow to change observedAttributes
+    if (!(attr in this.#attr)) {
+      return
+    }
+    const type = this.#getType(attr)
+    this.#attr[attr] = this.#changedAttr[attr] = newValue
+    console.debug('%s.setAttribute("%s",', this.nodeName, name, newValue)
+
+    // only set string values in these cases
+    if (type === 'Boolean') {
+      if (newValue === true || newValue === '') {
+        super.setAttribute(name, '')
+      } else {
+        super.removeAttribute(name)
+      }
+    } else if (['String', 'Number'].includes(type) || newValue === true) {
+      super.setAttribute(name, newValue)
+    } else {
+      this.requestUpdate()
+    }
+  }
+
+  /**
+   * request rendering
+   */
+  requestUpdate() {
+    if (!this.isConnected) return
+    requestAnimationFrame(() => {
+      if (this.shouldUpdate(this.#changedAttr)) {
+        this.update(this.#changedAttr)
+      }
+      // reset changed attributes
+      this.#changedAttr = {}
+    })
+  }
+
+  /**
+   * adds a template to renderRoot
+   * @param {HTMLTemplateElement}
+   */
+  addTemplate(template) {
+    if (!(template instanceof HTMLTemplateElement)) {
+      console.debug('template is not a HTMLTemplateElement')
+      return
+    }
+    this.renderRoot.appendChild(template.content.cloneNode(true))
+  }
+
+  /**
+   * initial rendering
+   */
+  render() {}
+
+  /**
+   * controls if component shall be updated
+   * @param {Record<string,any>} _changedAttributes changed attributes
+   * @returns {boolean}
+   */
+  shouldUpdate(_changedAttributes) {
+    return true
+  }
+
+  /**
+   * called every time the components needs a render update
+   * @param {Record<string,any>} _changedAttributes changed attributes
+   */
+  update(_changedAttributes) {}
+
+  /**
+   * Adds listener function for eventName. listener is removed before component
+   * disconnects
+   * @param {string} eventName
+   * @param {EventListenerOrEventListenerObject} listener
+   * @param {Node|Document|Window} [node=this]
+   */
+  on(eventName, listener, node = this) {
+    node.addEventListener(eventName, listener)
+    this.#disposers.add(() => node.removeEventListener(eventName, listener))
+  }
+
+  /**
+   * Adds one-time listener function for eventName. The next time eventName is
+   * triggered, this listener is removed and then invoked.
+   * @param {string} eventName
+   * @param {EventListenerOrEventListenerObject} listener
+   * @param {Node|Document|Window} node
+   */
+  once(eventName, listener, node = this) {
+    node.addEventListener(eventName, listener, { once: true })
+  }
+
+  /**
+   * Unsubscribe a listener function for disposal on disconnectedCallback()
+   * @param {function} listener
+   */
+  dispose(listener) {
+    if (typeof listener !== 'function') {
+      throw new TypeError('listener must be a function')
+    }
+    this.#disposers.add(listener)
+  }
+
+  /**
+   * adds a connected controller
+   * @param {HostController} controller
+   */
+  addController(controller) {
+    this.#controllers.add(controller)
+    if (this.isConnected) {
+      // if already connected call hostConnected() immediately
+      /* istanbul ignore next */
+      controller.hostConnected?.()
+    }
+  }
+
+  /**
+   * removes a connected controller
+   * @param {HostController} controller
+   */
+  /* istanbul ignore next 3 */
+  removeController(controller) {
+    this.#controllers.delete(controller)
+  }
+}
+
+/**
+ * defines a custom element adding observedAttributes from default static
+ * attributes
+ * NOTE: camelCased attributes get lowercased!
+ * ```html
+ * <custom-element myAttr="1">
+ * <!-- is equal to -->
+ * <custom-element myattr="1">
+ * ```
+ * @param {string} name custom element tag
+ * @param {typeof MiElement} element
+ * @param {object} [options]
+ */
+export const define = (name, element, options) => {
+  // @ts-expect-error
+  element.observedAttributes = // @ts-expect-error
+    (element.observedAttributes || Object.keys(element.attributes || [])).map(
+      (attr) => attr.toLowerCase()
+    )
+  renderTemplate(element)
+  window.customElements.define(name, element, options)
+}
+
+// --- utils
+
+const renderTemplate = (element) => {
+  if (typeof element.template !== 'string') {
+    return
+  }
+  const el = document.createElement('template')
+  el.innerHTML = element.template
+  element.template = el
+}
+
+const initialType = (value) => toString.call(value).slice(8, -1)
+
+const toNumber = (any) => {
+  const n = Number(any)
+  return isNaN(n) ? any : n
+}
+
+export const convertType = (any, type) => {
+  // setAttribute prevents passing Object or Array type. no further conversion required
+  switch (type) {
+    case 'Number':
+      return toNumber(any)
+    case 'Boolean':
+      // boolean values are set via setAttribute as empty string
+      if (any === 'false') {
+        return false
+      }
+      return any === '' || !!any
+  }
+  return any
+}

package/src/escape.js

@@ -0,0 +1,38 @@
+const escMap = {
+  '&': '&',
+  '<': '&lt;',
+  '>': '&gt;',
+  "'": '&#39;',
+  '"': '&quot;'
+}
+
+/**
+ * escape HTML and prevent double escaping of '&'
+ * @param {string} string - which requires escaping
+ * @returns {string} escaped string
+ * @example
+ * escapeHTML('<h1>"One" & 'Two' &amp; Works</h1>')
+ * //> &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])
+
+/**
+ * template literal to HTML escape all values preventing XSS
+ * @param {string[]} strings
+ * @param  {...any} vars
+ * @returns {string}
+ */
+export const esc = (strings, ...vars) =>
+  strings.map((string, i) => string + escHtml(vars[i] ?? '')).join('')

package/src/index.js

@@ -0,0 +1,22 @@
+/**
+ * @typedef {import('./context.js').Context} Context
+ */
+export {
+  ContextConsumer,
+  ContextProvider,
+  ContextRequestEvent
+} from './context.js'
+/**
+ * @typedef {import('./element.js').HostController} HostController
+ */
+export { MiElement, convertType, define } from './element.js'
+export { esc, escAttr, escHtml } from './escape.js'
+export { refsById, refsBySelector } from './refs.js'
+/**
+ * @typedef {import('./signal.js').Callback} Callback
+ */
+export { Signal, createSignal, isSignalLike } from './signal.js'
+/**
+ * @typedef {import('./store.js').Action} Action
+ */
+export { Store, subscribeToStore } from './store.js'

package/src/refs.js

@@ -0,0 +1,47 @@
+/**
+ * Helper function to find `id` attributes in `container`s node tree.
+ * id names are camelCased, e.g. 'list-container' becomes 'listContainer'
+ * @param {Element} container root element
+ * @returns {Record<string, Node>|{}} record of found references
+ * @example
+ * el.innerHTML = `<p id>unnamed <span id="named">and named</span> reference</p>`
+ * references = refs(el)
+ * //> references = { p: <p>, named: <span> }
+ */
+export function refsById(container) {
+  const nodes = container.querySelectorAll?.('[id]') || []
+  const found = {}
+  for (const node of nodes) {
+    const name = kebabToCamelCase(
+      node.getAttribute('id') || node.nodeName.toLowerCase()
+    )
+    found[name] = node
+  }
+  return found
+}
+
+/**
+ * convert kebab-case to lowerCamelCase
+ * @param {string} str
+ * @returns {string}
+ */
+export const kebabToCamelCase = (str = '') =>
+  str.toLowerCase().replace(/[-_]\w/g, (m) => m[1].toUpperCase())
+
+/**
+ * Helper function to gather references by a map of selectors
+ * @param {Element} container root element
+ * @param {Record<string, string>} selectors
+ * @returns {Record<string, Node>|{}}
+ * @example
+ * el.innerHTML = `<p>some <span>and other</span> reference</p>`
+ * references = refs(el, { p: 'p', named: 'p > span' })
+ * //> references = { p: <p>, named: <span> }
+ */
+export function refsBySelector(container, selectors) {
+  const found = {}
+  for (const [name, selector] of Object.entries(selectors)) {
+    found[name] = container.querySelector?.(selector)
+  }
+  return found
+}

package/src/signal.js

@@ -0,0 +1,76 @@
+/**
+ * @typedef {(value: any) => void} Callback
+ */
+
+export class Signal {
+  _subscribers = new Set()
+
+  /**
+   * creates a new signal with an initial value
+   * @param {any} [initialValue]
+   */
+  constructor(initialValue) {
+    this._value = initialValue
+  }
+
+  /**
+   * return current value
+   * @returns {any}
+   */
+  get value() {
+    return this._value
+  }
+
+  /**
+   * set new value on signal;
+   * if value has changed all subscribers are called
+   * @param {any} newValue
+   */
+  set value(newValue) {
+    // value or reference must have changed to notify subscribers
+    if (this._value === newValue) {
+      return
+    }
+    this._value = newValue
+    this.notify()
+  }
+
+  /**
+   * notify all subscribers on current value
+   */
+  notify() {
+    for (const callback of this._subscribers) {
+      callback(this._value)
+    }
+  }
+
+  /**
+   * subscribe to signal to receive value updates
+   * @param {Callback} callback
+   * @returns {() => void} unsubscribe function
+   */
+  subscribe(callback) {
+    this._subscribers.add(callback)
+    const unsubscribe = () => {
+      this._subscribers.delete(callback)
+    }
+    return unsubscribe
+  }
+}
+
+/**
+ * creates a signal
+ * @param {any} [initialValue]
+ * @returns {Signal}
+ */
+export const createSignal = (initialValue) => new Signal(initialValue)
+
+/**
+ * check if implements signal like features
+ * @param {any} possibleSignal
+ * @returns {boolean}
+ */
+export const isSignalLike = (possibleSignal) =>
+  typeof possibleSignal?.subscribe === 'function' &&
+  typeof possibleSignal?.notify === 'function' &&
+  'value' in possibleSignal

package/src/store.js

@@ -0,0 +1,99 @@
+import { Signal, isSignalLike } from './signal.js'
+
+/**
+ * @typedef {import('./element.js').MiElement} MiElement
+ */
+/**
+ * @typedef {(state: any, data?: any) => any} Action
+ */
+
+/**
+ * Store implementing [Flux](https://www.npmjs.com/package/flux) pattern based
+ * on Signals
+ */
+export class Store extends Signal {
+  /**
+   * @param {Record<string, Action>} actions
+   * @param {any} [initialValue]
+   * @example
+   * ```js
+   * const actions = { increment: (by = 1) => (current) => current + by }
+   * const initialValue = 1
+   * const store = new Store(actions, initialValue)
+   * // subscribe with a callback function
+   * const unsubscribe = store.subscribe((value) => console.log(`count is ${value}`))
+   * // 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
+   * using the spread operator, in order to notify on state changes, e.g.
+   * ```js
+   * const initialValue = { count: 0, other: 'foo' }
+   * const actions = {
+   *  increment: (by = 1) => (state) => ({...state, count: state.count + by})
+   * }
+   * ```
+   */
+  constructor(actions, initialValue) {
+    super(initialValue)
+    for (const [action, dispatcher] of Object.entries(actions)) {
+      if (process.env.NODE_ENV !== 'production') {
+        if (this[action]) {
+          throw new Error(`action "${action}" is already defined`)
+        }
+        if (
+          typeof dispatcher !== 'function' ||
+          typeof dispatcher(undefined) !== 'function'
+        ) {
+          throw new Error(
+            `action "${action}" must be a function of type \`() => (state) => state\``
+          )
+        }
+      }
+      this[action] = (data) => {
+        this.value = dispatcher(data)(this.value)
+      }
+    }
+  }
+}
+
+/**
+ * subscribe to a store from a MiElement with unsubscription from store on
+ * disconnectedCallback()
+ * @param {MiElement} element
+ * @param {Store} store
+ * @param {string|string[]|Signal} propOrSignal element property to apply store
+ * value updates
+ */
+export const subscribeToStore = (element, store, propOrSignal) => {
+  if (propOrSignal instanceof Signal || isSignalLike(propOrSignal)) {
+    element.dispose(
+      store.subscribe((value) => {
+        // @ts-expect-error
+        propOrSignal.value = value
+      })
+    )
+    return
+  }
+  const keys = Array.isArray(propOrSignal)
+    ? propOrSignal
+    : propOrSignal.split('.').filter(Boolean)
+  const last = keys.pop()
+  if (!last) throw TypeError('need prop')
+  let tmp = element
+  for (const key of keys) {
+    if (typeof tmp[key] !== 'object') {
+      throw new TypeError(`object expected for property "${key}"`)
+    }
+    tmp = tmp[key]
+  }
+  element.dispose(
+    store.subscribe((value) => {
+      tmp[last] = value
+      element.requestUpdate()
+    })
+  )
+}

package/types/context.d.ts

@@ -0,0 +1,70 @@
+/**
+ * @implements {HostController}
+ */
+export class ContextProvider implements HostController {
+  /**
+   * @param {MiElement} host
+   * @param {Context} context
+   * @param {any} initialValue
+   */
+  constructor(host: MiElement, context: Context, initialValue: any)
+  host: import('./element.js').MiElement
+  context: Context
+  state: any
+  hostConnected(): void
+  hostDisconnected(): void
+  set value(newValue: any)
+  get value(): any
+  notify(): void
+  onContextRequest: (ev: any) => void
+}
+export class ContextRequestEvent extends Event {
+  /**
+   * @param {Context} context
+   * @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
+  )
+  context: Context
+  callback: (value: any, unsubscribe?: () => void) => void
+  subscribe: boolean | undefined
+}
+/**
+ * @implements {HostController}
+ */
+export class ContextConsumer implements HostController {
+  /**
+   * @param {MiElement} host
+   * @param {Context} context
+   * @param {object} [options]
+   * @param {boolean} [options.subscribe=false] subscribe to value changes
+   * @param {(any) => boolean} [options.validate] validation function
+   */
+  constructor(
+    host: MiElement,
+    context: Context,
+    options?:
+      | {
+          subscribe?: boolean | undefined
+          validate?: ((any: any) => boolean) | undefined
+        }
+      | undefined
+  )
+  host: import('./element.js').MiElement
+  context: Context
+  subscribe: boolean
+  validate: (any: any) => boolean
+  value: any
+  unsubscribe: any
+  hostConnected(): void
+  hostDisconnected(): void
+  dispatchRequest(): void
+  _callback(value: any, unsubscribe: any): void
+}
+export type HostController = import('./element.js').HostController
+export type MiElement = import('./element.js').MiElement
+export type Context = string | Symbol