@knowark/componarkjs 1.14.0 → 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,21 +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)
   }
 
   /**
@@ -28,7 +38,7 @@ export class Component extends globalThis.HTMLElement {
 
   /**
    * @param {object} context
-   * @return {Component} */
+   * @return {this} */
   init (context = {}) {
     return this
   }
@@ -45,6 +55,7 @@ export class Component extends globalThis.HTMLElement {
   /** @param {string} content */
   set content (content) {
     this.innerHTML = content
+    this._needsBinding = true
   }
 
   /** @return {string} */
@@ -52,41 +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', error)
+          this.emit('error', this._enhanceError(error, 'load'))
         })
       }
     } catch (error) {
-      this.emit('error', error)
+      this.emit('error', this._enhanceError(error, 'load'))
       throw error
     }
   }
 
+  /** @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 {Component} */
+  /** @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
@@ -108,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)

package/lib/base/component/component.test.js

@@ -64,6 +64,44 @@ class PlainLoadComponent extends Component {
 }
 Component.define('plain-load-component', PlainLoadComponent)
 
+class StringLoadComponent extends Component {
+  load () {
+    throw 'String Load Error!'
+  }
+}
+Component.define('string-load-component', StringLoadComponent)
+
+class CleanupComponent extends Component {
+  init (context = {}) {
+    this.cleanupCalls = 0
+    return super.init(context)
+  }
+
+  render () {
+    return super.render()
+  }
+}
+Component.define('cleanup-component', CleanupComponent)
+
+class OptimizedListenerComponent extends Component {
+  init (context = {}) {
+    this.clicks = 0
+    return super.init(context)
+  }
+
+  render () {
+    if (!this.querySelector('button')) {
+      this.content = '<button listen on-click="onClick">Click me</button>'
+    }
+    return super.render()
+  }
+
+  onClick () {
+    this.clicks += 1
+  }
+}
+Component.define('optimized-listener-component', OptimizedListenerComponent)
+
 let container = null
 let component = null
 
@@ -166,6 +204,10 @@ it('catches and re-raises connectedCallback errors', async () => {
   const component = /** @type {Component} */ (
     document.createElement('mock-component'))
   const consoleErrorMock = mock.method(console, 'error', () => {})
+  let errorEvent = null
+  component.addEventListener('error', (event) => {
+    errorEvent = event
+  })
   component.render = () => {
     throw new Error('Render Error!')
   }
@@ -174,14 +216,72 @@ it('catches and re-raises connectedCallback errors', async () => {
     component.connectedCallback()
   } catch (error) {
     assert.deepStrictEqual(error.message, 'Render Error!')
+    assert.deepStrictEqual(errorEvent.detail.phase, 'init-render')
+    assert.deepStrictEqual(errorEvent.detail.component, 'MOCK-COMPONENT')
   } finally {
     consoleErrorMock.mock.restore()
   }
 })
 
-it('emits an error event when async load fails', async () => {
-  setup()
-  const component = document.createElement('async-load-component')
+  it('creates events without CustomEvent and keeps event details', () => {
+    setup()
+    const component = container.querySelector('mock-component')
+  const previousCustomEvent = globalThis.CustomEvent
+
+  try {
+    globalThis.CustomEvent = undefined
+    let detail = null
+    component.addEventListener('fallback-emit', (event) => {
+      detail = event.detail
+    })
+
+    component.emit('fallback-emit', { ready: true })
+
+    assert.deepStrictEqual(detail, { ready: true })
+    } finally {
+      globalThis.CustomEvent = previousCustomEvent
+    }
+  })
+
+  it('creates events from the component global window Event fallback', () => {
+    setup()
+    const component = document.createElement('mock-component')
+    const previousGlobal = component.global
+
+    try {
+      component.global = {
+        document: {
+          defaultView: {
+            Event: globalThis.Event
+          }
+        }
+      }
+
+      const event = component._createEvent('context-window-event', { ready: true })
+
+      assert.deepStrictEqual(event.type, 'context-window-event')
+      assert.deepStrictEqual(event.detail.ready, true)
+      assert.deepStrictEqual(typeof event.stopPropagation, 'function')
+    } finally {
+      component.global = previousGlobal
+    }
+  })
+
+  it('creates events from globalThis CustomEvent when component global has no window objects', () => {
+    setup()
+    const component = document.createElement('mock-component')
+
+    component.global = {}
+    const event = component._createEvent('global-custom-event', { ready: true })
+
+    assert.deepStrictEqual(event.type, 'global-custom-event')
+    assert.deepStrictEqual(event.detail.ready, true)
+    assert.deepStrictEqual(event instanceof globalThis.CustomEvent, true)
+  })
+
+  it('emits an error event when async load fails', async () => {
+    setup()
+    const component = document.createElement('async-load-component')
   let errorEvent = null
 
   component.addEventListener('error', (event) => {
@@ -194,6 +294,8 @@ it('emits an error event when async load fails', async () => {
 
   assert.ok(errorEvent)
   assert.deepStrictEqual(errorEvent.detail.message, 'Async Load Error!')
+  assert.deepStrictEqual(errorEvent.detail.phase, 'load')
+  assert.deepStrictEqual(errorEvent.detail.component, 'ASYNC-LOAD-COMPONENT')
 })
 
 it('emits an error event and throws when sync load fails', () => {
@@ -211,6 +313,176 @@ it('emits an error event and throws when sync load fails', () => {
 
   assert.ok(errorEvent)
   assert.deepStrictEqual(errorEvent.detail.message, 'Sync Load Error!')
+  assert.deepStrictEqual(errorEvent.detail.phase, 'load')
+  assert.deepStrictEqual(errorEvent.detail.component, 'SYNC-LOAD-COMPONENT')
+})
+
+it('coerces non-error load failures into errors with metadata', () => {
+  setup()
+  const component = document.createElement('string-load-component')
+  let errorEvent = null
+
+  component.addEventListener('error', (event) => {
+    errorEvent = event
+  })
+
+  assert.throws(() => {
+    component.connectedCallback()
+  }, /String Load Error!/)
+
+  assert.ok(errorEvent)
+  assert.deepStrictEqual(errorEvent.detail.message, 'String Load Error!')
+  assert.deepStrictEqual(errorEvent.detail.phase, 'load')
+  assert.deepStrictEqual(errorEvent.detail.component, 'STRING-LOAD-COMPONENT')
+})
+
+it('creates resolve events without CustomEvent and still resolves', () => {
+  setup()
+  const component = document.createElement('mock-component')
+  const previousCustomEvent = globalThis.CustomEvent
+
+  try {
+    globalThis.CustomEvent = undefined
+    let resource = null
+    component.addEventListener('resolve', (event) => {
+      resource = event.detail.resource
+    })
+
+    const result = component.resolve('dependency')
+
+    assert.deepStrictEqual(resource, 'dependency')
+    assert.strictEqual(result, undefined)
+  } finally {
+    globalThis.CustomEvent = previousCustomEvent
+  }
+})
+
+it('creates fallback events when neither CustomEvent nor Event are available', () => {
+  setup()
+  const component = document.createElement('mock-component')
+  const previousCustomEvent = globalThis.CustomEvent
+  const previousEvent = globalThis.Event
+
+  try {
+    globalThis.CustomEvent = undefined
+    globalThis.Event = undefined
+
+    component.global = {}
+    const event = component._createEvent('fallback', { ready: true })
+
+    assert.deepStrictEqual(event.type, 'fallback')
+    assert.deepStrictEqual(event.detail, { ready: true })
+    assert.deepStrictEqual(typeof event.stopPropagation, 'function')
+    assert.deepStrictEqual(typeof event.preventDefault, 'function')
+    assert.doesNotThrow(() => event.stopPropagation())
+    assert.doesNotThrow(() => event.preventDefault())
+  } finally {
+    globalThis.CustomEvent = previousCustomEvent
+    globalThis.Event = previousEvent
+  }
+})
+
+it('falls back to globalThis when component global is missing', () => {
+  setup()
+  const component = document.createElement('mock-component')
+  const previousCustomEvent = globalThis.CustomEvent
+
+  try {
+    globalThis.CustomEvent = undefined
+    component.global = null
+
+    const event = component._createEvent('global-fallback', { ready: true })
+
+    assert.deepStrictEqual(event.type, 'global-fallback')
+    assert.deepStrictEqual(event.detail.ready, true)
+  } finally {
+    globalThis.CustomEvent = previousCustomEvent
+  }
+})
+
+it('registers and runs cleanup callbacks on disconnect', () => {
+  setup()
+  const component = document.createElement('cleanup-component')
+  container.appendChild(component)
+
+  let cleanupCalls = 0
+  component.registerCleanup(() => {
+    cleanupCalls += 1
+  })
+  component.registerCleanup(() => {
+    cleanupCalls += 1
+  })
+
+  component.disconnectedCallback()
+
+  assert.deepStrictEqual(cleanupCalls, 2)
+})
+
+it('supports unregistering cleanup callbacks', () => {
+  setup()
+  const component = document.createElement('cleanup-component')
+  container.appendChild(component)
+
+  let cleanupCalls = 0
+  const unregister = component.registerCleanup(() => {
+    cleanupCalls += 1
+  })
+  unregister()
+  unregister()
+
+  component.disconnectedCallback()
+
+  assert.deepStrictEqual(cleanupCalls, 0)
+})
+
+it('supports disconnected init fast-path when local state is already set', () => {
+  setup()
+  const component = document.createElement('mock-component')
+  component.local = { preset: true }
+  const initSpy = mock.method(component, 'init')
+  container.appendChild(component)
+
+  assert.deepStrictEqual(initSpy.mock.calls.length, 0)
+  initSpy.mock.restore()
+})
+
+it('returns unchanged values when enhanced error details are absent', () => {
+  setup()
+  const component = document.createElement('cleanup-component')
+
+  const result = component._enhanceError(undefined, 'init-render')
+
+  assert.strictEqual(result, undefined)
+})
+
+it('accepts non-function cleanup callbacks as no-op registrations', () => {
+  setup()
+  const component = document.createElement('cleanup-component')
+
+  const unregister = component.registerCleanup()
+
+  assert.doesNotThrow(() => unregister())
+})
+
+it('emits an error event when a cleanup callback throws', () => {
+  setup()
+  const component = document.createElement('cleanup-component')
+  container.appendChild(component)
+  let errorEvent = null
+
+  component.addEventListener('error', (event) => {
+    errorEvent = event
+  })
+  component.registerCleanup(() => {
+    throw new Error('Cleanup failed')
+  })
+
+  component.disconnectedCallback()
+
+  assert.ok(errorEvent)
+  assert.deepStrictEqual(errorEvent.detail.message, 'Cleanup failed')
+  assert.deepStrictEqual(errorEvent.detail.phase, 'cleanup')
+  assert.deepStrictEqual(errorEvent.detail.component, 'CLEANUP-COMPONENT')
 })
 
 it('supports load implementations that do not return promises', () => {
@@ -611,3 +883,24 @@ it('provides a styleNames utility function for setting styles', () => {
 
   assert.deepStrictEqual(result, 'background-primary shadow-small')
 })
+
+it('reuses listener bindings when content does not change', () => {
+  setup()
+  container.innerHTML = `
+  <optimized-listener-component></optimized-listener-component>
+  `
+  const component = container.querySelector('optimized-listener-component')
+
+  component.render()
+  component.querySelector('button').click()
+
+  component.render()
+  component.querySelector('button').click()
+
+  component.content = '<button listen on-click="onClick">Click me</button>'
+  component.render()
+  component.querySelector('button').click()
+
+  assert.deepStrictEqual(component.clicks, 3)
+  assert.deepStrictEqual(component._needsBinding, false)
+})

package/lib/base/component/index.js

@@ -1,3 +1,6 @@
 export { Component } from './component.js'
+
+/** @type {typeof String.raw} */
 export const css = String.raw
+/** @type {typeof String.raw} */
 export const html = String.raw