@knowark/componarkjs 1.14.0 → 1.14.2

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/README.md

@@ -0,0 +1,127 @@
+# Component
+
+`Component` is the base class for Componark custom elements. It extends `HTMLElement` with:
+
+- Declarative event bindings (`listen` + `on-*` attributes)
+- Attribute-to-property reflection
+- Dependency resolution through bubbling `resolve` events
+- Cleanup registration for disconnect lifecycle
+
+## Usage
+
+```javascript
+import { Component } from 'base/component'
+
+class MyComponent extends Component {
+  reflectedProperties () {
+    return ['title']
+  }
+
+  init (context = {}) {
+    this.local.count = this.local.count ?? 0
+    return super.init(context)
+  }
+
+  increment () {
+    this.local.count += 1
+    this.render()
+  }
+
+  render () {
+    this.content = `
+      <button listen on-click="increment">
+        ${this.title}: ${this.local.count}
+      </button>
+    `
+    return super.render()
+  }
+
+  async load (_context = {}) {
+    // Optional async work after render.
+  }
+}
+
+Component.define('my-component', MyComponent)
+```
+
+## Lifecycle
+
+1. `constructor()`
+   - Initializes internal state (`binding`, `local`, cleanup registry, etc.).
+   - Applies reflected properties using `reflectedProperties()`.
+2. `connectedCallback()`
+   - Marks the component as connected.
+   - Calls `init({})` only when `local` is empty.
+   - Calls `render()`.
+   - Calls `load({})` (sync or async).
+3. `disconnectedCallback()`
+   - Marks the component as disconnected.
+   - Runs registered cleanup callbacks.
+
+Errors from `init`/`render`, `load`, and cleanup callbacks are emitted as bubbling `error` events. Enhanced errors include:
+
+- `phase`: `init-render`, `load`, or `cleanup`
+- `component`: current tag name (for example, `MY-COMPONENT`)
+
+## Public API
+
+### Static API
+
+| Method | Description |
+| --- | --- |
+| `Component.define(tagName, element, styles?)` | Registers a custom element. If `styles` are provided, they are registered for that tag. |
+
+### Instance API
+
+| Member | Returns | Description |
+| --- | --- | --- |
+| `init(context = {})` | `this` | Component state initialization hook. |
+| `reflectedProperties()` | `string[]` | Attribute names to expose as reflected properties. |
+| `slots` | `Record<string, HTMLElement[]>` | Child elements grouped by `slot` (`general` by default). |
+| `content` | `string` | Proxy for `innerHTML`. Setting it flags listeners for re-binding. |
+| `render()` | `this` | Adds the tag-name class and binds declarative listeners when needed. |
+| `load(context = {})` | `void \| Promise<void>` | Async hook called after `render()`. |
+| `registerCleanup(callback)` | `() => void` | Registers disconnect cleanup and returns an unregister function. |
+| `select(selector)` | `Component` | `querySelector` helper. |
+| `selectAll(selector)` | `NodeListOf<Component>` | `querySelectorAll` helper. |
+| `emit(type, detail)` | `void` | Dispatches a bubbling, cancelable event with `detail`. |
+| `resolve(resource)` | `any` | Requests a dependency through a bubbling `resolve` event. |
+| `styleNames(styleMap)` | `string` | Returns truthy class names from an object map. |
+
+## Declarative listeners
+
+`render()` triggers listener wiring on descendants marked with `listen`.
+
+```html
+<input listen on-input="{{ local.query = data }}">
+<input listen on-input="{{ local.total = data | number }}">
+<button listen on-click="submit"></button>
+<button listen on-click="submit@#child"></button>
+<div listen on-change="replaceChildren%detail.name@#target"></div>
+```
+
+Rules:
+
+- Use `on-<event>` attributes to define handlers.
+- `{{ ... }}` expressions perform state assignment.
+- Pipes support `string`, `number`, `boolean`, and `object`.
+- `handler@<selector>` routes execution to another element/component.
+- Handler failures emit bubbling `error` events.
+
+## Dependency resolution
+
+`resolve(resource)` dispatches a bubbling `resolve` event with `{ resource }`. Ancestors can provide values by implementing `provide(resource)`.
+
+```javascript
+class ParentComponent extends Component {
+  provide (resource) {
+    if (resource === 'state') return this.local
+  }
+}
+```
+
+Then in a child:
+
+```javascript
+const state = this.resolve('state')
+```

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)