@knowark/componarkjs 1.13.4 → 1.14.1

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

@@ -1,20 +1,43 @@
 // @ts-nocheck
 
+const stylesheetRegistry = new Map()
+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 = '') {
-  globalThis.customElements.define(tag, element)
+  const definedElement = globalThis.customElements.get(tag)
+  if (!definedElement) {
+    globalThis.customElements.define(tag, element)
+  }
   if (!styles?.trim()) return
+  if (typeof document === 'undefined') return
 
   try {
-    const sheet = new globalThis.CSSStyleSheet()
+    let sheet = stylesheetRegistry.get(tag)
+    if (!sheet) {
+      sheet = new globalThis.CSSStyleSheet()
+      stylesheetRegistry.set(tag, sheet)
+    }
     sheet.replaceSync(styles)
-    return (document.adoptedStyleSheets = [
-      ...document.adoptedStyleSheets, sheet])
+
+    const adopted = document.adoptedStyleSheets || []
+    if (!adopted.includes(sheet)) {
+      document.adoptedStyleSheets = [...adopted, sheet]
+    }
+
+    return sheet
   } catch (error) {
-    const style = document.createElement('style')
+    let style = fallbackRegistry.get(tag)
+    if (!style) {
+      style = document.createElement('style')
+      style.setAttribute('data-componark-tag', tag)
+      fallbackRegistry.set(tag, style)
+      document.head.appendChild(style)
+    }
     style.textContent = styles
-    document.head.appendChild(style)
+    return style
   }
 }

package/lib/base/utils/define.test.js

@@ -1,62 +1,149 @@
-import { jest } from '@jest/globals'
+import { it, mock } from 'node:test'
+import assert from 'node:assert/strict'
 import { define } from './define.js'
 
-describe('Define', () => {
-  it('can define a custome element', () => {
-    class NewElement extends globalThis.HTMLElement {}
-    define('new-element', NewElement)
+it('can define a custome element', () => {
+  class NewElement extends globalThis.HTMLElement {}
+  define('new-element', NewElement)
 
-    const newElement = document.createElement('new-element')
-    expect(newElement).toBeTruthy()
-  })
+  const newElement = document.createElement('new-element')
+  assert.ok(newElement)
+})
 
-  it('can define a custom element using constructable CSSStyleSheet', () => {
-    let definedStyles = null
-    class MockCSSStyleSheet extends globalThis.CSSStyleSheet {
-      replaceSync (styles) {
-        definedStyles = styles
-      }
+it('can define a custom element using constructable CSSStyleSheet', () => {
+  let definedStyles = null
+  class MockCSSStyleSheet extends globalThis.CSSStyleSheet {
+    replaceSync (styles) {
+      definedStyles = styles
     }
+  }
 
-    jest.spyOn(window, 'CSSStyleSheet').mockReturnValue(
-      new MockCSSStyleSheet())
-
-    class CSSStyledElement extends globalThis.HTMLElement {}
-    const styles = `
-    body {
-      color: red;
+  const cssStyleSheetSpy = mock.method(
+    globalThis,
+    'CSSStyleSheet',
+    function () {
+      return new MockCSSStyleSheet()
     }
+  )
+
+  class CSSStyledElement extends globalThis.HTMLElement {}
+  const styles = `
+  body {
+    color: red;
+  }
+
+  div {
+    margin: 5px;
+  }
+  `
+
+  define('css-styled-element', CSSStyledElement, styles)
 
-    div {
-      margin: 5px;
+  const styledElement = document.createElement('css-styled-element')
+  assert.ok(styledElement)
+
+  assert.deepStrictEqual(styles, definedStyles)
+  cssStyleSheetSpy.mock.restore()
+})
+
+it('can define a custom element using an style fallback element', () => {
+  const cssStyleSheetSpy = mock.method(
+    globalThis,
+    'CSSStyleSheet',
+    function () {
+      throw new Error('Constructable stylesheets are unavailable')
     }
-    `
+  )
+
+  class StyledElement extends globalThis.HTMLElement {}
+  const styles = `
+  body {
+    color: red;
+  }
+
+  div {
+    margin: 5px;
+  }
+  `
+
+  define('styled-element', StyledElement, styles)
+  cssStyleSheetSpy.mock.restore()
 
-    define('css-styled-element', CSSStyledElement, styles)
+  const styledElement = document.createElement('styled-element')
+  assert.ok(styledElement)
+  const style = Array.from(document.head.querySelectorAll('style')).find(
+    (item) => item.textContent.includes('color: red;')
+  )
+  assert.ok(style)
+})
 
-    const styledElement = document.createElement('css-styled-element')
-    expect(styledElement).toBeTruthy()
+it('does not throw when defining an already defined custom element', () => {
+  class DuplicateElement extends globalThis.HTMLElement {}
+  define('duplicate-element', DuplicateElement)
 
-    expect(styles).toEqual(definedStyles)
+  assert.doesNotThrow(() => {
+    define('duplicate-element', DuplicateElement)
   })
+})
 
-  it('can define a custom element using an style fallback element', () => {
-    class StyledElement extends globalThis.HTMLElement {}
-    const styles = `
-    body {
-      color: red;
+it('reuses fallback styles for repeated definitions of the same tag', () => {
+  const cssStyleSheetSpy = mock.method(
+    globalThis,
+    'CSSStyleSheet',
+    function () {
+      throw new Error('Constructable stylesheets are unavailable')
     }
+  )
+
+  class ReusedStyledElement extends globalThis.HTMLElement {}
+
+  define('reused-styled-element', ReusedStyledElement, 'body { color: red; }')
+  define('reused-styled-element', ReusedStyledElement, 'body { color: blue; }')
+
+  cssStyleSheetSpy.mock.restore()
+
+  const styles = Array.from(
+    document.head.querySelectorAll('style[data-componark-tag="reused-styled-element"]')
+  )
+  assert.deepStrictEqual(styles.length, 1)
+  assert.ok(styles[0].textContent.includes('color: blue;'))
+})
 
-    div {
-      margin: 5px;
+it('does not add a constructable stylesheet more than once for the same tag', () => {
+  class MockCSSStyleSheet extends globalThis.CSSStyleSheet {
+    replaceSync (_styles) {}
+  }
+  const cssStyleSheetSpy = mock.method(
+    globalThis,
+    'CSSStyleSheet',
+    function () {
+      return new MockCSSStyleSheet()
     }
-    `
+  )
+  class OnceStyledElement extends globalThis.HTMLElement {}
 
-    define('styled-element', StyledElement, styles)
+  const beforeCount = document.adoptedStyleSheets.length
+  define('once-styled-element', OnceStyledElement, 'body { color: orange; }')
+  const firstCount = document.adoptedStyleSheets.length
+  define('once-styled-element', OnceStyledElement, 'body { color: green; }')
+  const secondCount = document.adoptedStyleSheets.length
 
-    const styledElement = document.createElement('styled-element')
-    expect(styledElement).toBeTruthy()
-    const style = document.head.querySelector('style')
-    expect(style).toBeTruthy()
-  })
+  cssStyleSheetSpy.mock.restore()
+  assert.deepStrictEqual(firstCount, beforeCount + 1)
+  assert.deepStrictEqual(secondCount, firstCount)
+})
+
+it('returns early when styles are provided but document is unavailable', () => {
+  const previousDocument = globalThis.document
+  class NoDocumentElement extends globalThis.HTMLElement {}
+
+  delete globalThis.document
+
+  try {
+    assert.doesNotThrow(() => {
+      define('no-document-element', NoDocumentElement, 'body { color: red; }')
+    })
+  } finally {
+    globalThis.document = previousDocument
+  }
 })

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/format.test.js

@@ -1,19 +1,19 @@
+import { it } from 'node:test';
+import assert from 'node:assert/strict';
 import { camelToKebab, kebabToCamel, snakeToCamel } from './format.js'
 
-describe('Format', () => {
-  it('can convert camel to kebab', () => {
-    const camel = 'myVariable'
-    const kebab = camelToKebab(camel)
-    expect(kebab).toBe('my-variable')
-  })
-  it('can convert kebab to camel', () => {
-    const kebab = 'my-variable'
-    const camel = kebabToCamel(kebab)
-    expect(camel).toBe('myVariable')
-  })
-  it('can convert snake to camel', () => {
-    const kebab = 'my_variable'
-    const camel = snakeToCamel(kebab)
-    expect(camel).toBe('myVariable')
-  })
+it('can convert camel to kebab', () => {
+  const camel = 'myVariable'
+  const kebab = camelToKebab(camel)
+  assert.strictEqual(kebab, 'my-variable')
+})
+it('can convert kebab to camel', () => {
+  const kebab = 'my-variable'
+  const camel = kebabToCamel(kebab)
+  assert.strictEqual(camel, 'myVariable')
+})
+it('can convert snake to camel', () => {
+  const kebab = 'my_variable'
+  const camel = snakeToCamel(kebab)
+  assert.strictEqual(camel, 'myVariable')
 })

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
@@ -25,8 +32,11 @@ export function listen (self) {
             if (pipe?.toLocaleLowerCase() === 'object') {
               return set(this, objectPath.trim(), event.detail)
             }
-            set(this, objectPath.trim(), transform(pipe, get(
-              event, eventPath, get(event, 'detail', ''))))
+            const inputValue = (
+              get(event, eventPath, undefined) ||
+              get(event, 'detail', '')
+            )
+            set(this, objectPath.trim(), transform(pipe, inputValue))
           }
         }
 
@@ -59,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
@@ -99,9 +113,16 @@ 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
 
   pathArray.reduce((accumulator, key, index) => {
     if (accumulator[key.trim()] === undefined) accumulator[key.trim()] = {}
@@ -110,15 +131,27 @@ 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
 
-  return pathArray.reduce((accumulator, key) => accumulator &&
-    accumulator[key.trim()], object) || fallback
+  const value = pathArray.reduce((accumulator, key) => accumulator &&
+    accumulator[key.trim()], object)
+
+  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(' ')