@knowark/componarkjs 1.13.4 → 1.14.1

package/README.md

@@ -1,11 +1,11 @@
 <p align="center">
   <a href="https://codecov.io/gh/librark/componark">
-    <img src="https://codecov.io/gh/librark/componark/graph/badge.svg?token=IWNapsPUch"/>
+    <img src="https://codecov.io/gh/librark/componark/graph/badge.svg?token=IWNapsPUch" alt="codecov" />
   </a>
 </p>
 <p align="center">
   <a href="https://codecov.io/gh/librark/componark">
-    <img src="https://codecov.io/gh/librark/componark/graphs/sunburst.svg?token=IWNapsPUch"/>
+    <img src="https://codecov.io/gh/librark/componark/graphs/sunburst.svg?token=IWNapsPUch" alt="coverage sunburst" />
   </a>
 </p>
 
@@ -13,46 +13,58 @@
 
 Pragmatic Web Components Library
 
-Introduction
-============
-
-Componark is a collection of ready to use web components to propel the creation
-of user interfaces. A common *Component* base class is provided to ensure
-inter-component compatibility and common development idioms. This class is only
-a thin wrapper on top of the *HTMLElement* custom elements class, and might be
-extended in your own application code to create new components.
-
-Reference
-=========
-
-- `Base Component <lib/base/component>`_
-
-Components library
-------------------
-
-- `<ark-accordion> <lib/components/accordion>`_
-- `<ark-alert> <lib/components/alert>`_
-- `<ark-audio> <lib/components/audio>`_
-- `<ark-button> <lib/components/button>`_
-- `<ark-camera> <lib/components/camera>`_
-- `<ark-card> <lib/components/card>`_
-- `<ark-chart> <lib/components/chart>`_
-- `<ark-checkbox> <lib/components/checkbox>`_
-- `<ark-droparea> <lib/components/droparea>`_
-- `<ark-gallery> <lib/components/gallery>`_
-- `<ark-icon> <lib/components/icon>`_
-- `<ark-list> <lib/components/list>`_
-- `<ark-input> <lib/components/input>`_
-- `<ark-location> <lib/components/location>`_
-- `<ark-map> <lib/components/map>`_
-- `<ark-modal> <lib/components/modal>`_
-- `<ark-multiselect> <lib/components/multiselect>`_
-- `<ark-paginator> <lib/components/paginator>`_
-- `<ark-radio> <lib/components/radio>`_
-- `<ark-select> <lib/components/select>`_
-- `<ark-sidebar> <lib/components/sidebar>`_
-- `<ark-signature> <lib/components/signature>`_
-- `<ark-spinner> <lib/components/spinner>`_
-- `<ark-splitview> <lib/components/splitview>`_
-- `<ark-tabs> <lib/components/tabs>`_
-- `<ark-tooltip> <lib/components/tooltip>`_
+## Introduction
+
+ComponArk is a lightweight Web Components library with a shared base class for
+consistency and event-driven composition.
+
+The library is organized as custom elements that can be used directly in HTML or
+combined with your application code.
+
+## Reference
+
+- [Base Component](lib/base/component)
+- [Showcase](showcase)
+
+## Components library
+
+> Components marked in **bold** are available in this repository.
+
+- **`ark-audio`** ([docs](lib/components/audio/README.md))
+- **`ark-camera`** ([docs](lib/components/camera/README.md))
+- **`ark-capture`** ([docs](lib/components/capture/README.md))
+- **`ark-droparea`** ([docs](lib/components/droparea/README.md))
+- **`ark-emit`** ([docs](lib/components/emit/README.md))
+- **`ark-list`** ([docs](lib/components/list/README.md))
+- **`ark-paginator`** ([docs](lib/components/paginator/README.md))
+- **`ark-spinner`** ([docs](lib/components/spinner/README.md))
+- **`ark-splitview`** ([docs](lib/components/splitview/README.md))
+- **`ark-translate`** ([docs](lib/components/translate/README.md))
+
+## Why this exists
+
+- Minimal, reusable base (`Component`) with lifecycle hooks and dependency
+  resolution.
+- Template/event binding helper (`listen`) with custom attribute syntax.
+- Lightweight styling support with constructor stylesheet + fallback support.
+- Small test surface included with native Node test runner.
+
+## Basic usage
+
+```html
+<ark-translate languages="en,es"></ark-translate>
+
+<span data-i18n="hello">Hello</span>
+```
+
+## Development
+
+- Run tests: `npm test`
+- Build production bundle: `npm run prod`
+- Start local dev server: `npm run dev`
+
+## Notes
+
+Some older docs in the previous release referenced components that are not in the
+current snapshot of this repository. If you need one of those modules, check
+the release tags or open a request with expected parity.

package/lib/base/component/component.js

@@ -2,20 +2,31 @@ import { define, listen, reflect, slot, keys } from '../utils/index.js'
 import styles from '../styles/index.js'
 
 const tag = 'ark-component'
+/**
+ * Base composable UI component.
+ * @extends {globalThis.HTMLElement}
+ */
 export class Component extends globalThis.HTMLElement {
   constructor () {
     super()
     this.binding = 'listen'
     this.local = {}
+    this._isConnected = false
+    this._cleanupCallbacks = []
+    this._needsBinding = true
+    this.global = globalThis
     reflect(this, this.reflectedProperties())
   }
 
   /**
-   * @param {string} tag
+   * Register a custom element and optional CSS for the same tag.
+   * @param {string} tagName
    * @param {CustomElementConstructor} element
-   * @param {string} styles **/
-  static define (tag, element, styles = null) {
-    define(tag, element, styles)
+   * @param {string} [styles]
+   * @returns {void}
+   */
+  static define (tagName, element, styles = null) {
+    define(tagName, element, styles)
   }
 
   /**
@@ -27,7 +38,7 @@ export class Component extends globalThis.HTMLElement {
 
   /**
    * @param {object} context
-   * @return {Component} */
+   * @return {this} */
   init (context = {}) {
     return this
   }
@@ -44,6 +55,7 @@ export class Component extends globalThis.HTMLElement {
   /** @param {string} content */
   set content (content) {
     this.innerHTML = content
+    this._needsBinding = true
   }
 
   /** @return {string} */
@@ -51,26 +63,62 @@ export class Component extends globalThis.HTMLElement {
     return this.innerHTML
   }
 
+  /** @returns {void} */
   connectedCallback () {
+    this._isConnected = true
     try {
       !Boolean(Object.keys(this.local).length) && this.init({})
       this.render()
     } catch (error) {
-      this.emit('error', error)
+      this.emit('error', this._enhanceError(error, 'init-render'))
+      throw error
+    }
+    try {
+      const load = this.load({})
+      if (load && typeof load.catch === 'function') {
+        load.catch(error => {
+          this.emit('error', this._enhanceError(error, 'load'))
+        })
+      }
+    } catch (error) {
+      this.emit('error', this._enhanceError(error, 'load'))
       throw error
     }
-    this.load({})
   }
 
-  /** @return {Component} */
+  /** @returns {void} */
+  disconnectedCallback () {
+    this._isConnected = false
+    this._cleanup()
+  }
+
+  /**
+   * @param {Function} callback
+   * @return {Function} */
+  registerCleanup (callback) {
+    if (!callback || typeof callback !== 'function') return () => {}
+
+    this._cleanupCallbacks.push(callback)
+    return () => {
+      const index = this._cleanupCallbacks.indexOf(callback)
+      if (index === -1) return
+      this._cleanupCallbacks.splice(index, 1)
+    }
+  }
+
+  /** @return {this} */
   render () {
     this.classList.add(this.tagName.toLowerCase())
-    listen(this)
+    if (this._needsBinding) {
+      listen(this)
+      this._needsBinding = false
+    }
     return this
   }
 
-  /** @param {object} context */
-  async load (context = {}) {}
+  /** @param {object} context
+   * @returns {void | Promise<void>} */
+  load (context = {}) {}
 
   /**
    * @param {string} selectors
@@ -92,26 +140,100 @@ export class Component extends globalThis.HTMLElement {
    * @param {string} type
    * @param {any} detail */
   emit (type, detail) {
-    this.dispatchEvent(
-      new globalThis.CustomEvent(type, {
-        detail,
-        bubbles: true,
-        cancelable: true
-      })
-    )
+    this.dispatchEvent(this._createEvent(type, detail, {
+      bubbles: true,
+      cancelable: true
+    }))
   }
 
   /**
    * @param {string} resource
    * @return {any} */
   resolve (resource) {
-    const event = new globalThis.CustomEvent('resolve', {
-      detail: { resource },
+    const event = this._createEvent('resolve', { resource }, {
       bubbles: true,
       cancelable: true
     })
     this.dispatchEvent(event)
     return event.detail[resource]
   }
+
+  /**
+   * @param {any} detail
+   * @param {string} phase
+   * @return {Error} */
+  _enhanceError (detail, phase) {
+    if (!detail) return detail
+
+    const error = detail instanceof Error ? detail : new Error(
+      `${detail.message || detail}`
+    )
+    /** @type {Error & { phase?: string, component?: string }} */
+    const enhancedError = error
+    enhancedError.phase = phase
+    enhancedError.component = this.tagName
+    return error
+  }
+
+  /** @returns {void} */
+  _cleanup () {
+    const callbacks = [...this._cleanupCallbacks]
+    this._cleanupCallbacks = []
+
+    for (const callback of callbacks) {
+      try {
+        callback()
+      } catch (error) {
+        this.emit('error', this._enhanceError(error, 'cleanup'))
+      }
+    }
+  }
+
+  /**
+   * Creates an event object for dispatch.
+   * @param {string} type
+   * @param {any} detail
+   * @param {{ bubbles?: boolean, cancelable?: boolean }} [options]
+   * @returns {CustomEvent}
+   */
+  _createEvent (type, detail, options = {}) {
+    /** @type {{ [key: string]: any }} */
+    const contextGlobal = this.global || {}
+    const contextWindow = contextGlobal.document?.defaultView || contextGlobal.window || contextGlobal
+    const { bubbles = true, cancelable = true } = options
+
+    if (typeof contextWindow.CustomEvent === 'function') {
+      return new contextWindow.CustomEvent(type, { detail, bubbles, cancelable })
+    }
+
+    if (typeof contextWindow.Event === 'function') {
+      const event = new contextWindow.Event(type, { bubbles, cancelable })
+      ;(/** @type {any} */ (event)).detail = detail
+      return /** @type {CustomEvent} */ (event)
+    }
+
+    if (typeof globalThis.CustomEvent === 'function') {
+      return new globalThis.CustomEvent(type, { detail, bubbles, cancelable })
+    }
+
+    if (typeof globalThis.Event === 'function') {
+      const event = new globalThis.Event(type, { bubbles, cancelable })
+      ;(/** @type {any} */ (event)).detail = detail
+      return /** @type {CustomEvent} */ (event)
+    }
+
+    return /** @type {CustomEvent} */ (/** @type {unknown} */ ({
+      type,
+      detail,
+      bubbles,
+      cancelable,
+      currentTarget: this,
+      defaultPrevented: false,
+      cancelBubble: false,
+      target: this,
+      stopPropagation () {},
+      preventDefault () {}
+    }))
+  }
 }
 Component.define(tag, Component, styles)