mi-element 0.0.1 → 0.1.0

package/types/element.d.ts

@@ -0,0 +1,169 @@
+/**
+ * @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 {
+  /**
+   * Default options used when calling `attachShadow`. Used in
+   * `connectedCallback()`.
+   * If override is `null`, no shadow-root will be attached.
+   */
+  static shadowRootOptions: {
+    mode: string
+  }
+  __attr: {}
+  __attrLc: Map<any, any>
+  __types: Map<any, any>
+  __disposers: Set<any>
+  __controllers: Set<any>
+  __changedAttr: {}
+  /**
+   * requests update on component when property changes
+   */
+  __observedAttributes(): void
+  /**
+   * return camelCased value instead of possible lowercased
+   * @param {string} name
+   * @returns
+   */
+  __getName(name: string): any
+  __getType(name: any): any
+  /**
+   * creates the element's renderRoot, sets up styling
+   * @category lifecycle
+   */
+  connectedCallback(): void
+  renderRoot: any
+  /**
+   * unsubscribe from all events and disconnect controllers
+   */
+  disconnectedCallback(): void
+  /**
+   * @param {string} name change attribute
+   * @param {any} _oldValue
+   * @param {any} newValue new value
+   */
+  attributeChangedCallback(name: string, _oldValue: any, newValue: any): void
+  /**
+   * 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: string, newValue: any): void
+  /**
+   * request rendering
+   */
+  requestUpdate(): void
+  /**
+   * initial rendering
+   */
+  render(): void
+  /**
+   * controls if component shall be updated
+   * @param {Record<string,any>} _changedAttributes changed attributes
+   * @returns {boolean}
+   */
+  shouldUpdate(_changedAttributes: Record<string, any>): boolean
+  /**
+   * called every time the components needs a render update
+   * @param {Record<string,any>} _changedAttributes changed attributes
+   */
+  update(_changedAttributes: Record<string, any>): void
+  /**
+   * 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: string,
+    listener: EventListenerOrEventListenerObject,
+    node?: Node | Document | Window | undefined
+  ): void
+  /**
+   * 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: string,
+    listener: EventListenerOrEventListenerObject,
+    node?: Node | Document | Window
+  ): void
+  /**
+   * Unsubscribe a listener function for disposal on disconnectedCallback()
+   * @param {function} listener
+   */
+  dispose(listener: Function): void
+  /**
+   * adds a connected controller
+   * @param {HostController} controller
+   */
+  addController(controller: HostController): void
+  /**
+   * removes a connected controller
+   * @param {HostController} controller
+   */
+  removeController(controller: HostController): void
+}
+export function define(
+  name: string,
+  element: typeof MiElement,
+  options?: object
+): void
+export function convertType(any: any, type: any): any
+/**
+ * controller
+ */
+export type HostController = {
+  /**
+   * is called when host element is added to
+   * the DOM, usually with connectedCallback()
+   */
+  hostConnected: () => void
+  /**
+   * is called when host element is
+   * removed from the DOM, usually with disconnectedCallback()
+   */
+  hostDisconnected: () => void
+}

package/types/escape.d.ts

@@ -0,0 +1,3 @@
+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

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

package/types/refs.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Helper function to find `id` attributes in `container`s node tree
+ * @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: Element): Record<string, Node> | {}
+/**
+ * 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: Element,
+  selectors: Record<string, string>
+): Record<string, Node> | {}

package/types/signal.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @typedef {(value: any) => void} Callback
+ */
+export class Signal {
+  /**
+   * creates a new signal with an initial value
+   * @param {any} [initialValue]
+   */
+  constructor(initialValue?: any)
+  _subscribers: Set<any>
+  _value: any
+  /**
+   * set new value on signal;
+   * if value has changed all subscribers are called
+   * @param {any} newValue
+   */
+  set value(newValue: any)
+  /**
+   * return current value
+   * @returns {any}
+   */
+  get value(): any
+  /**
+   * notify all subscribers on current value
+   */
+  notify(): void
+  /**
+   * subscribe to signal to receive value updates
+   * @param {Callback} callback
+   * @returns {() => void} unsubscribe function
+   */
+  subscribe(callback: Callback): () => void
+}
+export function createSignal(initialValue?: any): Signal
+export function isSignalLike(possibleSignal: any): boolean
+export type Callback = (value: any) => void

package/types/store.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @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: Record<string, Action>, initialValue?: any)
+}
+export function subscribeToStore(
+  element: MiElement,
+  store: Store,
+  prop: string | string[]
+): void
+export type MiElement = import('./element.js').MiElement
+export type Action = (state: any, data?: any) => any
+import { Signal } from './signal.js'