@knowark/componarkjs 1.14.0 → 1.14.1

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()

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

@@ -3,6 +3,9 @@ import { ListItem } from './item.js'
 
 const tag = 'ark-list'
 
+/**
+ * List component (array-driven rendering).
+ */
 export class List extends Component {
   constructor () {
     super()
@@ -10,7 +13,8 @@ export class List extends Component {
     this.addEventListener('delete', this._onDeleted.bind(this))
   }
 
-  /** @param {Object} context */
+  /** @param {object} context
+   *  @returns {this} */
   init (context = {}) {
     this.source = /** @type {Array} */ (context.source) || this.source || []
     this.template = context.template || this.template || ((data) => `${data}`)
@@ -18,6 +22,7 @@ export class List extends Component {
     return super.init()
   }
 
+  /** @returns {this} */
   render () {
     const listData = this.select('data')
     const list = this._parseJSON(listData?.textContent)
@@ -48,7 +53,10 @@ export class List extends Component {
     return super.render()
   }
 
-  /** @param {number} start @param {number?} deleteCount  */
+  /** @param {number} start
+   *  @param {number} [deleteCount=1]
+   *  @returns {void}
+   */
   delete (start, deleteCount = 1) {
     this.source.splice(start, deleteCount)
     const deletions = []
@@ -59,6 +67,8 @@ export class List extends Component {
     deletions.map(item => item.remove())
   }
 
+  /** @param {string} template
+   * @returns {(data: any)=>string} */
   _format (template) {
     let render = null
 
@@ -80,7 +90,8 @@ export class List extends Component {
     }
   }
 
-  /** @param {MouseEvent} event */
+  /** @param {MouseEvent} event
+   * @returns {void} */
   _onSelected (event) {
     event.stopImmediatePropagation()
 
@@ -101,7 +112,8 @@ export class List extends Component {
     )
   }
 
-  /** @param {MouseEvent} event */
+  /** @param {MouseEvent} event
+   * @returns {void} */
   _onDeleted (event) {
     event.stopImmediatePropagation()
 
@@ -112,6 +124,8 @@ export class List extends Component {
     this.delete(Number(item.index))
   }
 
+  /** @param {string|null} source
+   * @returns {any[]|null} */
   _parseJSON (source) {
     if (!source) return null
 

package/lib/components/list/index.js

@@ -1,2 +1,3 @@
+/** List and list-item components. */
 export { ListItem } from './components/item.js'
 export { List } from './components/list.js'

package/lib/components/paginator/components/paginator.js

@@ -2,7 +2,12 @@ import { Component } from '#base/index.js'
 import styles from '../styles/index.js'
 
 const tag = 'ark-paginator'
+/**
+ * Pagination control component.
+ */
 export class Paginator extends Component {
+  /** @param {object} context
+   *  @returns {this} */
   init (context = {}) {
     this.binding = 'paginator-listen'
     this.collectionSize = (
@@ -21,6 +26,7 @@ export class Paginator extends Component {
     return ['collectionSize', 'pageSize', 'displayedPages', 'currentPage']
   }
 
+  /** @returns {this} */
   render () {
     this._grabSlots()
     this.content = /* html */`
@@ -42,12 +48,13 @@ export class Paginator extends Component {
       this._buildButton(this.previousButton, '_prev', '<'))
 
     for (const page of this.currentPages) {
-      const attributes = [['data-page', page]]
+      /** @type {[string, string][]} */
+      const attributes = [['data-page', String(page)]]
       if ((Number(page) === Number(this.currentPage))) {
         attributes.unshift(['active', ''])
       }
       this.querySelector('[data-middle]').appendChild(
-        this._buildButton(this.pageButton, null, page, attributes))
+        this._buildButton(this.pageButton, null, `${page}`, attributes))
     }
 
     this.querySelector('[data-end]').appendChild(
@@ -58,10 +65,12 @@ export class Paginator extends Component {
     return super.render()
   }
 
+  /** @returns {number} */
   get totalPages () {
     return Math.ceil(this.collectionSize / this.pageSize)
   }
 
+  /** @returns {number[]} */
   get currentPages () {
     const displayedPages = Math.min(
       parseInt(this.displayedPages), this.totalPages)
@@ -72,6 +81,7 @@ export class Paginator extends Component {
     return Array.from({ length: displayedPages }, (_, i) => i + startPage)
   }
 
+  /** @returns {void} */
   _notifyChange () {
     const page = parseInt(this.currentPage)
     const limit = parseInt(this.pageSize)
@@ -80,6 +90,8 @@ export class Paginator extends Component {
   }
 
   /** @param {number} currentPage */
+  /** @param {number} currentPage
+   * @returns {void} */
   _setCurrentPage (currentPage) {
     if (currentPage > 0 && currentPage <= this.totalPages) {
       this.currentPage = currentPage
@@ -88,19 +100,22 @@ export class Paginator extends Component {
     }
   }
 
-  /** @param {Event} event */
+  /** @param {Event} event
+   * @returns {void} */
   _first (event) {
     event.stopPropagation()
     this._setCurrentPage(1)
   }
 
-  /** @param {Event} event */
+  /** @param {Event} event
+   * @returns {void} */
   _prev (event) {
     event.stopPropagation()
     this._setCurrentPage(parseInt(this.currentPage) - 1)
   }
 
-  /** @param {Event} event */
+  /** @param {Event} event
+   * @returns {void} */
   _move (event) {
     event.stopPropagation()
     const target = /** @type {HTMLElement} */ (event.target)
@@ -108,18 +123,21 @@ export class Paginator extends Component {
     this._setCurrentPage(page)
   }
 
-  /** @param {Event} event */
+  /** @param {Event} event
+   * @returns {void} */
   _next (event) {
     event.stopPropagation()
     this._setCurrentPage(parseInt(this.currentPage) + 1)
   }
 
-  /** @param {Event} event */
+  /** @param {Event} event
+   * @returns {void} */
   _last (event) {
     event.stopPropagation()
     this._setCurrentPage(this.totalPages)
   }
 
+  /** @returns {void} */
   _grabSlots() {
     const [pageButton] = [this.slots.page].flat()
     this.pageButton = this.pageButton ?? pageButton
@@ -133,8 +151,16 @@ export class Paginator extends Component {
     this.lastButton = this.lastButton ?? lastButton
   }
 
+  /**
+   * @param {HTMLButtonElement|null} element
+   * @param {string|null} handler
+   * @param {string} content
+   * @param {Array<[string,string]>} attributes
+   * @returns {HTMLButtonElement}
+   */
   _buildButton (element, handler, content, attributes = []) {
-    const button = (element ?? document.createElement('button')).cloneNode(true)
+    const button = /** @type {HTMLButtonElement} */ (
+      (element ?? document.createElement('button')).cloneNode(true))
     button.innerHTML = button.innerHTML || content
     if (handler) {
       button.setAttribute('paginator-listen', '')

package/lib/components/paginator/index.js

@@ -1 +1,2 @@
+/** Pagination controls component. */
 export { Paginator } from './components/paginator.js'

package/lib/components/paginator/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/spinner/components/spinner.js

@@ -2,7 +2,12 @@ import { Component } from '#base/index.js'
 import styles from '../styles/index.js'
 
 const tag = 'ark-spinner'
+/**
+ * Configurable loading spinner component.
+ */
 export class Spinner extends Component {
+  /** @param {object} context
+   *  @returns {this} */
   init (context = {}) {
     this.scale = context.scale || this.scale || '1'
     this.type = context.type || this.type || 'circle'
@@ -14,6 +19,7 @@ export class Spinner extends Component {
     return ['scale', 'type']
   }
 
+  /** @returns {this} */
   render () {
     this.innerHTML = /* html */ `
       ${this.spinnerType(this.type)}
@@ -22,6 +28,8 @@ export class Spinner extends Component {
     return super.render()
   }
 
+  /** @param {string} scale
+   * @returns {void} */
   setScale (scale) {
     this.style.setProperty('transform', `scale(${scale})`)
   }
@@ -31,6 +39,8 @@ export class Spinner extends Component {
     return this.querySelector('[data-loader]')
   }
 
+  /** @param {string} type
+   * @returns {string} */
   spinnerType (type) {
     let content = ''
 

package/lib/components/spinner/index.js

@@ -1 +1,2 @@
+/** Loading indicator component. */
 export { Spinner } from './components/spinner.js'

package/lib/components/spinner/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/splitview/components/splitview.detail.js

@@ -1,6 +1,9 @@
 import { Component } from "#base/index.js"
 
 const tag = 'ark-splitview-detail'
+/**
+ * Detail slot wrapper for split-view component.
+ */
 export class SplitViewDetail extends Component {
   constructor () {
     super()
@@ -8,6 +11,8 @@ export class SplitViewDetail extends Component {
       'close', this.onClose.bind(this))
   }
 
+  /** @param {object} context
+   *  @returns {this} */
   init (context = {}) {
     this.binding = 'splitview-detail-listen'
 
@@ -22,6 +27,7 @@ export class SplitViewDetail extends Component {
     return super.init(context)
   }
 
+  /** @returns {this} */
   render () {
     this.content = ''
     this.append(this.main)
@@ -29,16 +35,19 @@ export class SplitViewDetail extends Component {
     return super.render()
   }
 
-  /** @param {Event} event */
+  /** @param {Event} event
+   * @returns {void} */
   onClose (event) {
     event.stopPropagation()
     this.hide()
   }
 
+  /** @returns {void} */
   show () {
     this.removeAttribute('hidden')
   }
 
+  /** @returns {void} */
   hide () {
     this.setAttribute('hidden', '')
   }

package/lib/components/splitview/components/splitview.js

@@ -1,8 +1,12 @@
 import { Component, css } from "#base/index.js"
 
 /** @import {SplitViewDetail} from './splitview.detail.js' */
+/** @import {SplitViewMaster} from './splitview.master.js' */
 
 const tag = 'ark-splitview'
+/**
+ * Master-detail split view orchestrator.
+ */
 export class SplitView extends Component {
   constructor () {
     super()
@@ -12,6 +16,7 @@ export class SplitView extends Component {
     this._master = null
   }
 
+  /** @returns {void} */
   setDimensions () {
     if (typeof globalThis.innerHeight !== 'number') return
     if (typeof globalThis.innerWidth !== 'number') return
@@ -20,18 +25,21 @@ export class SplitView extends Component {
     this.style.setProperty('--inner-width', `${globalThis.innerWidth}px`)
   }
 
+  /** @returns {void} */
   connectedCallback () {
     this.setDimensions()
     globalThis.addEventListener('resize', this._onResize)
     super.connectedCallback()
   }
 
+  /** @returns {void} */
   disconnectedCallback () {
     globalThis.removeEventListener('resize', this._onResize)
     this._removeMasterListener()
     super.disconnectedCallback()
   }
 
+  /** @returns {void} */
   _setMasterListener () {
     const master = this.master
     if (master === this._master) return
@@ -41,34 +49,41 @@ export class SplitView extends Component {
     this._master?.addEventListener('master-change', this._onMasterChange)
   }
 
+  /** @returns {void} */
   _removeMasterListener () {
     if (!this._master) return
     this._master.removeEventListener('master-change', this._onMasterChange)
     this._master = null
   }
 
+  /** @returns {(SplitViewMaster|null)} */
   get master () {
-    return this.select('ark-splitview-master')
+    return /** @type {SplitViewMaster|null} */ (
+      this.querySelector('ark-splitview-master'))
   }
 
+  /** @returns {SplitViewDetail} */
   get detail () {
     return /** @type {SplitViewDetail} */ (this.select('ark-splitview-detail'))
   }
 
+  /** @returns {this} */
   render () {
     this.renderDetail()
     this._setMasterListener()
     return super.render()
   }
 
-  /** @param {Object} context */
+  /** @param {object} context
+   * @returns {void} */
   renderDetail (context = {}) {
     if (!this.detail || !this.detail.init) return
 
     this.detail.init(context).render()
   }
 
-  /** @param {CustomEvent} event */
+  /** @param {CustomEvent} event
+   * @returns {void} */
   onMasterChange (event) {
     event.stopPropagation()