@knowark/componarkjs 1.14.0 → 1.14.1

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

package/lib/components/capture/components/capture.js

@@ -1,6 +1,7 @@
 import { Component } from "#base/index.js"
 
 const tag = 'ark-capture'
+/** Template-driven renderer component. */
 export class Capture extends Component {
   constructor () {
     super()
@@ -12,7 +13,8 @@ export class Capture extends Component {
     return ['receive']
   }
 
-  /** @param {Object} context */
+  /** @param {object} context
+   *  @returns {this} */
   init (context = {}) {
     const data = this._parseJSON(this._pop(':scope > data')?.textContent)
     this.source = /** @type {object} */ (
@@ -23,6 +25,7 @@ export class Capture extends Component {
     return super.init()
   }
 
+  /** @returns {this} */
   render () {
     const outputTemplate = this._pop(':scope > template')?.innerHTML
     this.template = (
@@ -36,11 +39,16 @@ export class Capture extends Component {
     return super.render()
   }
 
+  /** @param {{detail:any}} event */
   handle (event) {
     const source = event.detail
     this.init({ source }).render()
   }
 
+  /**
+   * @param {string} template
+   * @returns {(data: any) => string}
+   */
   _format (template) {
     let render = null
 
@@ -62,12 +70,20 @@ export class Capture extends Component {
     }
   }
 
+  /**
+   * @param {string} selector
+   * @returns {HTMLElement|null}
+   */
   _pop (selector) {
     const element = this.querySelector(selector)
     element?.remove()
-    return element
+    return /** @type {HTMLElement|null} */ (element)
   }
 
+  /**
+   * @param {string|null} source
+   * @returns {object|null}
+   */
   _parseJSON (source) {
     if (!source) return null
 

package/lib/components/capture/index.js

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

package/lib/components/droparea/components/droparea-preview.js

@@ -4,6 +4,9 @@ import './droparea.js'
 /** @import {Droparea} from './droparea.js' */
 
 const tag = 'ark-droparea-preview'
+/**
+ * Renders file previews and drag-sort ordering.
+ */
 
 export class DropareaPreview extends Component {
   constructor () {
@@ -12,15 +15,19 @@ export class DropareaPreview extends Component {
     this._onDragEnd = this.handleDrop.bind(this)
   }
 
-  init (_context = {}) {
+  /** @param {object} context
+   *  @returns {this} */
+  init (context = {}) {
     return super.init()
   }
 
+  /** @returns {void} */
   disconnectedCallback () {
     this.revokeAllFiles()
     super.disconnectedCallback()
   }
 
+  /** @returns {this} */
   render () {
     this.content = /* html */ `
          <ul data-preview-list class="ark-droparea-preview__list drag-sort-enable"></ul>
@@ -28,6 +35,10 @@ export class DropareaPreview extends Component {
     return super.render()
   }
 
+  /**
+   * @param {File} file
+   * @returns {void}
+   */
   previewFile (file) {
     const blobUrl = this.getObjectURL(file)
     const fileType = file.type.split('/')[0]
@@ -58,6 +69,7 @@ export class DropareaPreview extends Component {
     }
   }
 
+  /** @returns {void} */
   toggleVisibility () {
     const previewZone = this.select('[data-preview-list]')
     this.files.length !== 0
@@ -67,6 +79,8 @@ export class DropareaPreview extends Component {
 
   /* DragSort Functionality */
 
+  /** @param {string} listClass
+   *  @returns {void} */
   enableDragSort (listClass) {
     const sortableLists = this.getElementsByClassName(listClass)
     Array.prototype.map.call(sortableLists, (list) => {
@@ -74,56 +88,69 @@ export class DropareaPreview extends Component {
     })
   }
 
+  /** @param {HTMLUListElement} list
+   *  @returns {void} */
   enableDragList (list) {
     Array.prototype.map.call(list.children, (item) => {
       this.enableDragItem(item)
     })
   }
 
+  /** @param {HTMLElement} item
+   *  @returns {void} */
   enableDragItem (item) {
     if (item.hasAttribute('data-drag-enabled')) return
 
     item.setAttribute('data-drag-enabled', '')
-    item.setAttribute('draggable', true)
+    item.setAttribute('draggable', 'true')
     item.addEventListener('drag', this.handleDrag.bind(this, item))
     item.addEventListener('dragend', this._onDragEnd, false)
   }
 
   /* istanbul ignore next */
+  /** @param {HTMLLIElement} item
+   * @param {DragEvent} event
+   * @returns {void} */
   handleDrag (item, event) {
     const selectedItem = item
-    const list = selectedItem.parentNode
+    const list = /** @type {HTMLElement} */ (selectedItem.parentElement)
     const x = event.clientX
     const y = event.clientY
 
     selectedItem.classList.add('drag-sort-active')
-    let swapItem =
-      document.elementFromPoint(x, y) === null
-        ? selectedItem
-        : document.elementFromPoint(x, y)
-    if (list === swapItem.parentNode) {
+    let swapItem = /** @type {ChildNode|null} */ (
+      document.elementFromPoint(x, y))
+    if (!swapItem) swapItem = selectedItem
+
+    if (list && swapItem && list === swapItem.parentNode) {
       swapItem = (
         swapItem !== selectedItem.nextSibling
           ? swapItem
           : swapItem.nextSibling)
-      list.insertBefore(selectedItem, swapItem)
+      list.insertBefore(selectedItem, /** @type {ChildNode|null} */ (swapItem))
     }
   }
 
+  /** @param {DragEvent} event
+   * @returns {void} */
   handleDrop (event) {
-    const droparea = event.target.closest('ark-droparea')
+    const target = /** @type {HTMLElement|null} */ (event.target)
+    if (!target) return
+    const droparea = /** @type {Droparea|null} */ (target.closest('ark-droparea'))
     if (!droparea) return
 
     droparea.preview.createNewFileList()
-    event.target.classList.remove('drag-sort-active')
+    target.classList.remove('drag-sort-active')
     droparea.preview.dispatchAlterEvent()
   }
   /* ---------------------------------------------------- */
 
+  /** @returns {void} */
   dispatchAlterEvent () {
     this.emit('alter', this.mediaList)
   }
 
+  /** @returns {void} */
   createNewFileList () {
     const nodeList = this.querySelectorAll('li')
     const newList = []
@@ -134,10 +161,16 @@ export class DropareaPreview extends Component {
     this.droparea.fileList = newList
   }
 
+  /**
+   * @param {File} file
+   * @returns {boolean}
+   */
   fileExists (file) {
     return this.files.some((item) => item.name === file.name)
   }
 
+  /** @param {File} file
+   * @returns {string} */
   getObjectURL (file) {
     if (this._objectUrls.has(file)) return this._objectUrls.get(file)
 
@@ -146,6 +179,8 @@ export class DropareaPreview extends Component {
     return url
   }
 
+  /** @param {File} file
+   * @returns {void} */
   revokeFile (file) {
     const url = this._objectUrls.get(file)
     if (!url) return
@@ -154,6 +189,7 @@ export class DropareaPreview extends Component {
     URL.revokeObjectURL?.(url)
   }
 
+  /** @returns {void} */
   revokeAllFiles () {
     for (const url of this._objectUrls.values()) {
       URL.revokeObjectURL?.(url)
@@ -161,20 +197,25 @@ export class DropareaPreview extends Component {
     this._objectUrls.clear()
   }
 
+  /** @returns {void} */
   clearPreview () {
     const previewZone = this.select('[data-preview-list]')
     previewZone && (previewZone.textContent = '')
     this.toggleVisibility()
   }
 
+  /** @param {File} file
+   * @param {MouseEvent} event
+   * @returns {void} */
   removeFile (file, event) {
-    const element = event.target
+    const element = /** @type {HTMLElement|null} */ (event.target)
+    if (!element) return
     const fileIndex = this.droparea.fileList.indexOf(file)
     if (fileIndex < 0) return
 
     this.revokeFile(file)
     this.droparea.fileList.splice(fileIndex, 1)
-    element.parentNode.remove()
+    element.parentElement?.remove()
     this.selectAll('li').forEach((item, index) =>
       item.setAttribute('index', String(index))
     )
@@ -182,14 +223,18 @@ export class DropareaPreview extends Component {
     this.dispatchAlterEvent()
   }
 
+  /** @param {File} file
+   * @returns {number} */
   fileIndex (file) {
     return this.droparea.fileList.indexOf(file)
   }
 
+  /** @returns {Droparea} */
   get droparea () {
     return /** @type {Droparea} */ (this.closest('ark-droparea'))
   }
 
+  /** @returns {Array<{name:string,type:string,size:number,url:string}>} */
   get mediaList () {
     const mediaList = []
     this.droparea.fileList.map((file) => {

package/lib/components/droparea/components/droparea-preview.test.js

@@ -287,3 +287,85 @@ it('does nothing when revoking a file without an object URL', () => {
     preview.revokeFile(file)
   })
 })
+
+it('renders a text preview in single mode and clears previous preview items', () => {
+  setup()
+  container.innerHTML = /* html */ `
+    <ark-droparea single></ark-droparea>
+  `
+  const droparea = container.querySelector('ark-droparea')
+  const dropZone = droparea.querySelector('.ark-droparea__form')
+  const firstFile = new File(['first'], 'first.txt', { type: 'text/plain' })
+  const secondFile = new File(['second'], 'second.txt', { type: 'text/plain' })
+
+  dropZone.dispatchEvent(createBubbledEvent('drop', {
+    dataTransfer: { files: [firstFile] }
+  }))
+
+  const firstPreviewItem = droparea.preview.querySelector('li')
+  assert.deepStrictEqual(firstPreviewItem.querySelector('p').textContent, 'first.txt')
+  assert.ok(firstPreviewItem.getAttribute('data').includes('mock://data/url/'))
+  assert.strictEqual(firstPreviewItem.getAttribute('index'), null)
+
+  dropZone.dispatchEvent(createBubbledEvent('drop', {
+    dataTransfer: { files: [secondFile] }
+  }))
+
+  const frames = droparea.preview.querySelectorAll('li')
+  assert.deepStrictEqual(frames.length, 1)
+  assert.deepStrictEqual(frames[0].querySelector('p').textContent, 'second.txt')
+})
+
+it('clearPreview tolerates missing preview list nodes', () => {
+  setup()
+  const preview = document.createElement('ark-droparea-preview')
+  const originalSelect = preview.select
+  preview.select = () => null
+  preview.toggleVisibility = () => {}
+
+  assert.doesNotThrow(() => {
+    preview.clearPreview()
+  })
+
+  preview.select = originalSelect
+})
+
+it('returns early when handleDrop receives a null target', () => {
+  setup()
+  const preview = document.createElement('ark-droparea-preview')
+
+  assert.doesNotThrow(() => {
+    preview.handleDrop({ target: null })
+  })
+})
+
+it('returns early when removeFile receives a null target', () => {
+  setup()
+  const preview = document.createElement('ark-droparea-preview')
+  const file = new File(['image'], 'Nully.png', { type: 'image/png' })
+
+  assert.doesNotThrow(() => {
+    preview.removeFile(file, { target: null })
+  })
+})
+
+it('revokeFile and revokeAllFiles tolerate missing revokeObjectURL', () => {
+  setup()
+  const preview = document.createElement('ark-droparea-preview')
+  const file = new File(['one'], 'one.txt', { type: 'text/plain' })
+  const secondFile = new File(['two'], 'two.txt', { type: 'text/plain' })
+  preview._objectUrls.set(file, 'mock://data/url/a')
+  preview._objectUrls.set(secondFile, 'mock://data/url/b')
+
+  const originalRevoke = global.URL.revokeObjectURL
+  global.URL.revokeObjectURL = undefined
+
+  try {
+    assert.doesNotThrow(() => {
+      preview.revokeFile(file)
+      preview.revokeAllFiles()
+    })
+  } finally {
+    global.URL.revokeObjectURL = originalRevoke
+  }
+})