@knowark/componarkjs 1.14.0 → 1.14.2

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

package/lib/base/styles/index.js

@@ -1,3 +1,6 @@
 import styles from './styles.js'
 
-export default styles
+/** @type {string} */
+const stylesText = styles
+
+export default stylesText

package/lib/base/utils/define.js

@@ -5,7 +5,8 @@ const fallbackRegistry = new Map()
 
 /** @param {string} tag
  * @param {CustomElementConstructor} element
- * @param {string} styles **/
+ * @param {string} [styles]
+ * @returns {CSSStyleSheet|HTMLStyleElement|undefined} */
 export function define (tag, element, styles = '') {
   const definedElement = globalThis.customElements.get(tag)
   if (!definedElement) {

package/lib/base/utils/format.js

@@ -1,13 +1,17 @@
 /**
- * Convert Strings from camelCase to kebab-case
- * @param {string} input @returns {string} */
+ * Convert Strings from camelCase to kebab-case.
+ * @param {string} input
+ * @returns {string}
+ */
 export function camelToKebab (input) {
   return input.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase()
 }
 
 /**
- * Convert Strings from kebab-case to camelCase
- * @param {string} input @returns {string} */
+ * Convert Strings from kebab-case to camelCase.
+ * @param {string} input
+ * @returns {string}
+ */
 export function kebabToCamel (input) {
   return input.replace(/-([a-z])/g, function (g) {
     return g[1].toUpperCase()
@@ -15,8 +19,10 @@ export function kebabToCamel (input) {
 }
 
 /**
- * Convert Strings from snake to camelCase
- * @param {string} input @returns {string} */
+ * Convert Strings from snake to camelCase.
+ * @param {string} input
+ * @returns {string}
+ */
 export function snakeToCamel (input) {
   return input.replace(/_([a-z])/g, function (g) {
     return g[1].toUpperCase()

package/lib/base/utils/helpers.js

@@ -1,6 +1,13 @@
+/**
+ * @import { Component } from '../component/component.js'
+ */
 import { camelToKebab } from './format.js'
 
-/** @param {HTMLElement} self */
+/**
+ * Binds declarative event handlers in descendant nodes for a component.
+ * @param {Component|HTMLElement} self
+ * @returns {void}
+ */
 export function listen (self) {
   /** @ts-ignore */
   const binding = self.binding
@@ -62,7 +69,11 @@ export function listen (self) {
   }
 }
 
-/** @param {HTMLElement} self  */
+/**
+ * Resolve dependencies from descendants using `resolve` events.
+ * @param {Component|HTMLElement} self
+ * @returns {void}
+ */
 function provide (self) {
   /** @ts-ignore */
   if (!self.provide) return
@@ -102,7 +113,13 @@ function transform (pipe, value) {
   }[pipe?.toLowerCase() || 'string'](value)
 }
 
-/** @param {object} object @param {string} path @param {any} value */
+/**
+ * Sets a nested property value by object path.
+ * @param {unknown} object
+ * @param {string} path
+ * @param {any} value
+ * @returns {void}
+ */
 export function set (object, path, value) {
   const pathArray = path.match(/([^[.\]])+/g)
   if (!pathArray?.length) return
@@ -114,7 +131,13 @@ export function set (object, path, value) {
   }, object)
 }
 
-/** @param {object} object @param {string} path @param {any} fallback */
+/**
+ * Reads a nested property value by path.
+ * @param {unknown} object
+ * @param {string} path
+ * @param {any} fallback
+ * @returns {any}
+ */
 export function get (object, path, fallback) {
   const pathArray = path.match(/([^[.\]])+/g)
   if (!pathArray?.length) return fallback
@@ -125,7 +148,10 @@ export function get (object, path, fallback) {
   return value === undefined ? fallback : value
 }
 
-/** @param {object} object @return {string} */
+/** @param {object} object
+ * @return {string}
+ * @description Returns truthy CSS class names from object values.
+ */
 export function keys (object) {
   return Object.keys(object).filter(
     key => Boolean(object[key])).join(' ')

package/lib/base/utils/index.js

@@ -1,3 +1,4 @@
+/** Utility helpers for component internals and runtime bindings. */
 export * from './define.js'
 export * from './format.js'
 export * from './helpers.js'

package/lib/base/utils/slots.js

@@ -1,7 +1,8 @@
 /**
+ * Groups child nodes by slot name.
  * @param {HTMLElement} container
- * @return {Object<string, Array<HTMLElement>>}
- * */
+ * @returns {Record<string, HTMLElement[]>}
+ */
 export function getSlots (container) {
   const slots = { general: [] }
 

package/lib/base/utils/uuid.js

@@ -1,4 +1,4 @@
-/** @returns {string} */
+/** @returns {string} Generated RFC-4122-like identifier. */
 export function uuid () {
   return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(
     /[xy]/g, function (c) {

package/lib/components/audio/components/audio.js

@@ -2,8 +2,16 @@ import { Component } from '#base/index.js'
 import styles from '../styles/index.js'
 
 const tag = 'ark-audio'
+/**
+ * Audio recorder component.
+ * Emits:
+ * - `error` with `Error` detail on capture/rendering issues.
+ */
 export class Audio extends Component {
+  /** @param {object} context
+   *  @returns {this} */
   init (context = {}) {
+    /** @type {'idle'|'recording'|'done'} */
     this.status = 'idle'
     this.dataURL = null
     this.timerId = null
@@ -18,6 +26,7 @@ export class Audio extends Component {
     return ['status']
   }
 
+  /** @returns {this} */
   render () {
     if (this.status === 'done') {
       this.content = `
@@ -45,7 +54,8 @@ export class Audio extends Component {
     return super.render()
   }
 
-  /** @param {Event} event */
+  /** @param {Event} event
+   *  @returns {Promise<void>} */
   async start (event) {
     event.stopPropagation()
     this.status = 'recording'
@@ -60,7 +70,8 @@ export class Audio extends Component {
     this.recorder.start()
   }
 
-  /** @param {Event} event */
+  /** @param {Event} event
+   *  @returns {void} */
   stop (event) {
     event.stopPropagation()
     this.status = 'done'
@@ -70,6 +81,7 @@ export class Audio extends Component {
     this.render()
   }
 
+  /** @returns {void} */
   reset () {
     clearInterval(this.timerId)
     this._revokeObjectURL()
@@ -80,6 +92,7 @@ export class Audio extends Component {
     this.recorder = null
   }
 
+  /** @returns {void} */
   disconnectedCallback () {
     clearInterval(this.timerId)
     this.recorder?.stream?.getTracks?.().forEach(track => track.stop())
@@ -87,6 +100,7 @@ export class Audio extends Component {
     super.disconnectedCallback()
   }
 
+  /** @returns {ReturnType<typeof setInterval>} Interval handle. */
   _time () {
     let count = 0
     return setInterval(() => {
@@ -113,6 +127,7 @@ export class Audio extends Component {
     reader.onloadend = () => { this.dataURL = reader.result }
   }
 
+  /** @returns {void} */
   _revokeObjectURL () {
     if (!this.objectURL) return
     this.global.URL.revokeObjectURL?.(this.objectURL)

package/lib/components/audio/index.js

@@ -1 +1,2 @@
+/** Audio recording component. */
 export { Audio } from './components/audio.js'

package/lib/components/audio/styles/index.js

@@ -1,2 +1,6 @@
 import styles from './ark.css.js'
-export default styles
+
+/** @type {string} */
+const stylesText = styles
+
+export default stylesText

package/lib/components/camera/components/camera.js

@@ -2,7 +2,12 @@ import { Component } from '#base/index.js'
 import styles from '../styles/index.js'
 
 const tag = 'ark-camera'
+/**
+ * Camera capture component.
+ */
 export class Camera extends Component {
+  /** @param {object} context
+   *  @returns {this} */
   init (context = {}) {
     this.width = this.width || context.width || 320
     this.height = this.height || context.height || 320
@@ -47,6 +52,7 @@ export class Camera extends Component {
     return canvas.toDataURL('image/jpg')
   }
 
+  /** @returns {Promise<void>} */
   async start () {
     const stream = await this.global.navigator.mediaDevices.getUserMedia({
       video: {
@@ -60,18 +66,22 @@ export class Camera extends Component {
     this.video.srcObject = stream
   }
 
+  /** @returns {void} */
   stop () {
     // @ts-ignore
     const tracks = this.video.srcObject ? this.video.srcObject.getTracks() : []
     tracks.forEach(track => track.stop())
   }
 
+  /** @param {string} facingMode
+   *  @returns {Promise<void>} */
   async setCameraOrientation (facingMode) {
     this.stop()
     this.facingMode = facingMode
     await this.start()
   }
 
+  /** @returns {void} */
   disconnectedCallback () {
     this.stop()
     super.disconnectedCallback()

package/lib/components/camera/index.js

@@ -1 +1,2 @@
+/** Camera capture component. */
 export { Camera } from './components/camera.js'

package/lib/components/camera/styles/index.js

@@ -1,2 +1,6 @@
 import styles from './ark.css.js'
-export default styles
+
+/** @type {string} */
+const stylesText = styles
+
+export default stylesText