@knowark/componarkjs 1.14.0 → 1.14.2

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

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

@@ -1,6 +1,9 @@
 import { Component } from "#base/index.js"
 
 const tag = 'ark-splitview-master'
+/**
+ * Master pane controller for split-view layout.
+ */
 export class SplitViewMaster extends Component {
   constructor () {
     super()
@@ -9,25 +12,31 @@ export class SplitViewMaster extends Component {
     this.masterEvent = this.masterEvent
   }
 
+  /** @param {object} context
+   *  @returns {this} */
   init (context = {}) {
     this.binding = 'splitview-master-listen'
     return super.init(context)
   }
 
+  /** @returns {string[]} */
   reflectedProperties () {
     return ['masterEvent']
   }
 
+  /** @returns {void} */
   connectedCallback () {
     this._syncMasterEventListener()
     super.connectedCallback()
   }
 
+  /** @returns {void} */
   disconnectedCallback () {
     this._removeMasterEventListener()
     super.disconnectedCallback()
   }
 
+  /** @returns {void} */
   _syncMasterEventListener () {
     const masterEvent = (this.masterEvent || '').trim()
     if (!masterEvent || masterEvent === this._boundMasterEvent) return
@@ -37,6 +46,7 @@ export class SplitViewMaster extends Component {
     this._boundMasterEvent = masterEvent
   }
 
+  /** @returns {void} */
   _removeMasterEventListener () {
     if (!this._boundMasterEvent) return
     this.removeEventListener(this._boundMasterEvent, this._onMasterEvent)

package/lib/components/splitview/index.js

@@ -1,3 +1,4 @@
+/** Master-detail split view components. */
 export { SplitViewDetail } from './components/splitview.detail.js'
 export { SplitViewMaster } from './components/splitview.master.js'
 export { SplitView } from './components/splitview.js'

package/lib/components/translate/components/translate.js

@@ -1,13 +1,24 @@
 import { Component } from "#base/index.js"
 
 const tag = 'ark-translate'
+ /**
+ * Translation component.
+ * @typedef {{key:string, namespace:string}} TranslatedKey
+ * @typedef {Record<string, Record<string, Record<string, string>>>} DictionaryStore
+ * @typedef {{language?:string, root?:string}} TransliterateOptions
+ */
 export class Translate extends Component {
+  /** @type {DictionaryStore} */
+  dictionary
+  /** @param {object} context
+   * @returns {this} */
   init (context = {}) {
     this.languages = this.languages
     this.global = context.global || window
     this.endpoint = context.endpoint || this.endpoint || '/locales'
     this.namespace = context.namespace || this.namespace || 'default'
     this.root = context.root || this.root || 'body'
+    /** @type {DictionaryStore} */
     this.dictionary = context.dictionary || {}
 
     const dictionary = (
@@ -15,7 +26,7 @@ export class Translate extends Component {
     if (dictionary) {
       const content = dictionary.content.textContent
       try {
-        this.dictionary = JSON.parse(content)
+        this.dictionary = /** @type {DictionaryStore} */ (JSON.parse(content))
       } catch (error) {
         this.emit('error', error)
       }
@@ -24,10 +35,12 @@ export class Translate extends Component {
     return super.init(context)
   }
 
+  /** @returns {string[]} */
   reflectedProperties () {
     return ['languages', 'endpoint', 'namespace', 'root']
   }
 
+  /** @returns {this} */
   render () {
     const languages = this.languages.split(',').filter(
       item => Boolean(item) && item.trim())
@@ -46,12 +59,17 @@ export class Translate extends Component {
     return super.render()
   }
 
+  /** @param {Event} event
+   * @returns {Promise<void>} */
   async onLanguageChanged (event) {
     event.stopPropagation()
-    const language = event.target.value
+    const target = /** @type {HTMLSelectElement|null} */ (event.target)
+    const language = target?.value
     await this.transliterate({ language })
   }
 
+  /** @param {TransliterateOptions} options
+   * @returns {Promise<void>} */
   async transliterate (options = {}) {
     const language = options.language || 'es'
     const root = this.global.document.querySelector(
@@ -67,12 +85,15 @@ export class Translate extends Component {
           language, namespace
         )
       )
-      const dictionary = dictionaries[namespace]
+      const dictionary = /** @type {Record<string, string>} */ (
+        dictionaries[namespace])
 
       node.textContent = dictionary[key] || node.textContent
     }
   }
 
+  /** @param {string} value
+   * @returns {TranslatedKey} */
   parseKey (value) {
     let key = value
     let namespace = this.namespace
@@ -86,26 +107,36 @@ export class Translate extends Component {
     return { key, namespace }
   }
 
+  /** @param {string} language
+   * @param {string} namespace
+   * @returns {Promise<Record<string,string>>} */
   async resolveDictionary (language, namespace) {
-    let dictionary = ((this.dictionary[language] ||
-        {})[namespace] || null)
+    /** @type {DictionaryStore} */
+    const translations = this.dictionary
+    /** @type {Record<string, string>|null} */
+    let dictionary = /** @type {Record<string, string>|null} */ (
+      /** @type {unknown} */ (translations[language]?.[namespace]) || null)
 
     if (dictionary !== null) return dictionary
 
-    if (!this.global.fetch) return {}
+    if (!this.global.fetch) return /** @type {Record<string, string>} */ ({})
 
     const url = `${this.endpoint}/${language}/${namespace}.json`
     try {
       const response = await this.global.fetch(url)
-      if (response.ok === false) return {}
-      dictionary = await response.json()
+      if (response.ok === false) return /** @type {Record<string, string>} */ ({})
+      dictionary = /** @type {Record<string, string>} */ (
+        await response.json())
     } catch (error) {
       this.emit('error', error)
-      return {}
+      return /** @type {Record<string, string>} */ ({})
     }
 
-    this.dictionary[language] || (this.dictionary[language] = {})
-    this.dictionary[language][namespace] = dictionary
+    const cache = /** @type {Record<string, Record<string, Record<string, string>>>} */ (
+      /** @type {unknown} */ (translations))
+    cache[language] = cache[language] || {}
+    cache[language][namespace] = /** @type {Record<string, string>} */ (
+      /** @type {unknown} */ (dictionary || {}))
 
     return dictionary
   }