@knowark/componarkjs 1.14.0 → 1.14.2

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
+  }
+})

package/lib/components/droparea/components/droparea.js

@@ -5,6 +5,11 @@ import './droparea-preview.js'
 /** @import {DropareaPreview} from './droparea-preview.js' */
 
 const tag = 'ark-droparea'
+/**
+ * Drag-and-drop and file input area.
+ * Emits:
+ * - `alter` with current media list details.
+ */
 
 export class Droparea extends Component {
   constructor () {
@@ -13,6 +18,8 @@ export class Droparea extends Component {
     this._onOpenInput = this.openInput.bind(this)
   }
 
+  /** @param {object} context
+   *  @returns {this} */
   init (context = {}) {
     this.fileList = []
     this.contextFiles = context.contextFiles || this.contextFiles || []
@@ -22,6 +29,7 @@ export class Droparea extends Component {
     return super.init()
   }
 
+  /** @returns {this} */
   render () {
     this._grabSlots()
     this.content = /* html */ `
@@ -43,10 +51,12 @@ export class Droparea extends Component {
     return super.render()
   }
 
+  /** @returns {string[]} */
   reflectedProperties () {
     return ['size', 'accept', 'maxSize', 'title']
   }
 
+  /** @returns {Promise<void>} */
   async load () {
     this._detachListeners()
 
@@ -72,11 +82,13 @@ export class Droparea extends Component {
     }
   }
 
+  /** @returns {void} */
   disconnectedCallback () {
     this._detachListeners()
     super.disconnectedCallback()
   }
 
+  /** @returns {void} */
   _detachListeners () {
     if (this.dragDropEvents) {
       this.dragDropEvents.forEach((eventName) => {
@@ -101,25 +113,35 @@ export class Droparea extends Component {
     this.openButton?.removeEventListener('click', this._onOpenInput)
   }
 
+  /** @param {Event} event
+   *  @returns {void} */
   openInput (event) {
     event.stopPropagation()
     const input = this.select('[data-input]')
     input.click()
   }
 
+  /** @param {Event} event
+   *  @returns {void} */
   preventDefaults (event) {
     event.preventDefault()
     event.stopPropagation()
   }
 
+  /** @param {Event} event
+   *  @returns {void} */
   highlight (event) {
     this.dropZone.classList.add('highlight')
   }
 
+  /** @param {Event} event
+   *  @returns {void} */
   unhighlight (event) {
     this.dropZone.classList.remove('highlight')
   }
 
+  /** @param {DragEvent} event
+   *  @returns {void} */
   handleDrop (event) {
     event.stopPropagation()
     const data = event.dataTransfer
@@ -127,13 +149,17 @@ export class Droparea extends Component {
     this.handleFiles(files)
   }
 
+  /** @param {Event} event
+   *  @returns {void} */
   onChange (event) {
     event.stopPropagation()
-    const input = event.target
+    const input = /** @type {HTMLInputElement} */ (event.target)
     const files = input.files
     this.handleFiles(files)
   }
 
+  /** @param {FileList|File[]} files
+   *  @returns {void} */
   handleFiles (files) {
     if (this.single) {
       files = [files[0]]
@@ -163,6 +189,10 @@ export class Droparea extends Component {
     this.preview.dispatchAlterEvent()
   }
 
+  /**
+   * @param {File[]|FileList} fileList
+   * @returns {boolean}
+   */
   validate (fileList) {
     if (!this.accept || this.accept.length === 0) return true
     const acceptList = this.accept.split(',').map(
@@ -186,15 +216,20 @@ export class Droparea extends Component {
     return true
   }
 
+  /** @param {File} file
+   * @returns {boolean} */
   maxSizeValidate (file) {
     return true
   }
 
+  /** @returns {void} */
   _grabSlots() {
     const [fileInput] = [this.slots.general].flat()
     this.fileInput = this.fileInput ?? fileInput
   }
 
+  /** @param {HTMLInputElement|undefined} element
+   * @returns {HTMLInputElement} */
   _buildFileInput (element) {
     const input = element ?? document.createElement('input')
     const attributes = [['class', `${tag}__input`],
@@ -203,14 +238,18 @@ export class Droparea extends Component {
     return input
   }
   
+  /** @returns {HTMLFormElement} */
   get dropZone () {
-    return this.select('.ark-droparea__form')
+    return /** @type {HTMLFormElement} */ (
+      this.querySelector('.ark-droparea__form'))
   }
 
+  /** @returns {DropareaPreview} */
   get preview () {
     return /** @type {DropareaPreview} */ (this.select('ark-droparea-preview'))
   }
 
+  /** @returns {Array<{name:string,type:string,size:number,url:string}>} */
   get mediaList () {
     return this.preview.mediaList
   }

package/lib/components/droparea/index.js

@@ -1 +1,2 @@
+/** Drag-and-drop file input area components. */
 export { Droparea } from './components/droparea.js'

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

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

package/lib/components/emit/components/emit.js

@@ -1,6 +1,9 @@
 import { Component } from "#base/index.js"
 
 const tag = 'ark-emit'
+/**
+ * Declarative event forwarding component.
+ */
 export class Emit extends Component {
   constructor () {
     super()
@@ -15,6 +18,8 @@ export class Emit extends Component {
     return ['receive', 'dispatch', 'bind']
   }
 
+  /** @param {CustomEvent} event
+   * @returns {void} */
   handle (event) {
     const detail = Object.assign({}, event.detail)
 
@@ -27,19 +32,22 @@ export class Emit extends Component {
 
     Object.assign(detail, data)
 
-    const value = event.target.value
+    const value = /** @type {HTMLInputElement|null} */ (event.target)?.value
     if (value) Object.assign(detail, { value })
 
     const type = this.dispatch || 'emit'
     this.emit(type, detail)
   }
 
+  /** @param {string} selector
+   * @returns {Element|null} */
   _pop (selector) {
     const element = this.querySelector(selector)
     element?.remove()
     return element
   }
 
+  /** @returns {any|null} */
   _resolveBoundData () {
     const element = this.closest(this.bind)
     if (!element) return null
@@ -52,6 +60,8 @@ export class Emit extends Component {
     }
   }
 
+  /** @param {string} source
+   * @returns {object|null} */
   _parseJSON (source) {
     try {
       return JSON.parse(source)

package/lib/components/emit/index.js

@@ -1 +1,2 @@
+/** Event emitter bridge component. */
 export { Emit } from './components/emit.js'

package/lib/components/index.js

@@ -1,3 +1,4 @@
+/** Aggregated component exports. */
 export * from './audio/index.js'
 export * from './camera/index.js'
 export * from './capture/index.js'
@@ -6,4 +7,4 @@ export * from './list/index.js'
 export * from './paginator/index.js'
 export * from './spinner/index.js'
 export * from './splitview/index.js'
-export * from './translate/index.js'
+export * from './translate/index.js'

package/lib/components/list/components/item.js

@@ -1,7 +1,12 @@
 import { Component } from "#base/index.js"
 
 const tag = 'ark-list-item'
+/**
+ * Single list item for list component.
+ */
 export class ListItem extends Component {
+  /** @param {object} context
+   * @returns {this} */
   init (context = {}) {
     this.index = context.index
     this.data = context.data || null
@@ -14,6 +19,7 @@ export class ListItem extends Component {
     return ['index']
   }
 
+  /** @returns {this} */
   render () {
     this.content = this.template(this.data)
     return super.render()