@cntwg/html-helper 0.0.21 → 0.0.23

package/lib/html-ctrls/list.js

@@ -1,4 +1,4 @@
-// [v0.1.062-20240705]
+// [v0.1.067-20241119]
 
 // === module init block ===
 
@@ -10,9 +10,9 @@ const {
 
 const {
   isHTMLElement, isSelectedHTMLElement, isHiddenHTMLElement,
-  showHtmlElement, hideHtmlElement,
-  selectHtmlElement, unselectHtmlElement,
-  markHtmlElementAsCurrent, unmarkCurrentHtmlElement,
+  showHTMLElement, hideHTMLElement,
+  selectHTMLElement, unselectHTMLElement,
+  markHTMLElementAsCurrent, unmarkCurrentHTMLElement,
   readAsAttrValue, valueToClassList,
   CSS_CLASS_STRING,
 } = require('../html-helper-lib.js');
@@ -24,19 +24,25 @@ const {
 } = require('./mod-hfunc.js');
 
 const {
-  CSS_CLASS_SELECTED,
+  //CSS_CLASS_SELECTED,
   CSS_CLASS_DISABLED,
-  CSS_CLASS_HIDDEN,
-  CSS_CLASS_CURRENT,
-  CSS_CLASS_ACTIVE,
+  //CSS_CLASS_HIDDEN,
+  //CSS_CLASS_CURRENT,
+  //CSS_CLASS_ACTIVE,
 } = CSS_CLASS_STRING;
 
-const ILC_SMODE_DEF = 0;
-const ILC_SMODE_SHFT = 1;
-const ILC_SMODE_CTRL = 2;
-
 // === module extra block (helper functions) ===
 
+/**
+ * @function srchListElementByAttr
+ * @param {TItemsListEx} list
+ * @param {string} name
+ * @param {string} [value=""]
+ * @returns {object}
+ * @inner
+ * @description Searches an element in a list by a given attributes
+ *              of that element.
+ */
 function srchListElementByAttr(list, name, value = '') {
   const _value = readAsAttrValue(value);
   let item = null;
@@ -67,6 +73,10 @@ function srchListElementByAttr(list, name, value = '') {
  * (* constant definitions *)
  */
 
+const ILC_SMODE_DEF = 0;
+const ILC_SMODE_SHFT = 1;
+const ILC_SMODE_CTRL = 2;
+
 /***
  * (* function definitions *)
  */
@@ -76,20 +86,32 @@ function srchListElementByAttr(list, name, value = '') {
  */
 
 /**
- * @description This class implements an instance of a list container
+ * @classdesc This class implements an interfaco for a list container
  */
 class THtmlItemsListContainer {
-  #_host = null;
-  #_items = null;
-  #_options = null;
-  #_status = null;
+  /** @property {?HTMLElement} */
+  #_host;
+  /** @property {TItemsListEx} */
+  #_items;
+  /** @property {object} */
+  #_options;// = null;
+  /**
+   * @typedef {Object} statILCont
+   * @property {number} curIndex
+   * @property {?HTMLElement} curItem
+   * @inner
+   * @description A container status
+   */
+  /** @property {statILCont} */
+  #_status;
 
   /**
-   * @param {HTMLElement}
+   * @param {HTMLElement} host
    * @param {object} [opt]
-   * @param {bool} [opt.autoHideNewItems=false]
-   * @param {bool} [opt.markCurrentItem=false]
-   * @param {(string|array)} [opt.itemBaseClassID]
+   * @param {boolean} [opt.autoHideNewItems=false]
+   * @param {boolean} [opt.markCurrentItem=false]
+   * @param {(string|string[])} [opt.itemBaseClassID]
+   * @description Creates an instance of a list container
    */
   constructor(host, opt) {
     // check host
@@ -113,6 +135,7 @@ class THtmlItemsListContainer {
     itemBaseClassID = valueToClassList(itemBaseClassID, true);
     _options.itemBaseClassID = itemBaseClassID;
     // init status
+    /** @type {statILCont} */
     const _status = {
       curIndex: _items.curIndex,
       curItem: _items.curItem,
@@ -125,66 +148,72 @@ class THtmlItemsListContainer {
   /**
    * @property {number}
    * @readonly
+   * @description Contains a Qty of an elements
    */
-  get count(){
+  get count() {
     return this.#_items.count;
   }
 
   /**
-   * @property {index}
+   * @property {number}
    * @readonly
+   * @description Contains an of the current element
    */
-  get curIndex(){
+  get curIndex() {
     return this.#_items.curIndex;
   }
 
   /**
-   * @property {index}
+   * @property {number}
    * @readonly
+   * @description Returns a minimum value of an index
    */
-  get minIndex(){
+  get minIndex() {
     return this.#_items.minIndex;
   }
 
   /**
-   * @property {index}
+   * @property {number}
    * @readonly
+   * @description Returns a maximum value of an index
    */
-  get maxIndex(){
+  get maxIndex() {
     return this.#_items.maxIndex;
   }
 
   /**
-   * @property {index}
+   * @property {number}
    * @readonly
+   * @description Returns a value of a previous index
    */
-  get prevIndex(){
+  get prevIndex() {
     return this.#_items.prevIndex;
   }
 
   /**
-   * @property {index}
+   * @property {number}
    * @readonly
+   * @description Returns a value of a next index
    */
-  get nextIndex(){
+  get nextIndex() {
     return this.#_items.nextIndex;
   }
 
   /**
    * @property {?HTMLElement}
    * @readonly
+   * @description Returns an element in the current index
    */
-  get curItem(){
+  get curItem() {
     const item = this.#_items.curItem;
     return isHTMLElement(item) ? item : null;
   }
 
   /**
-   * @param {none}
-   * @returns {none}
+   * @returns {void}
    * @description Clears an instance content.
    */
-  clear(){
+  clear() {
     this.#_items.clear();
     const _status = this.#_status;
     _status.curIndex = this.curIndex;
@@ -194,104 +223,104 @@ class THtmlItemsListContainer {
   }
 
   /**
-   * @param {none}
-   * @returns {bool}
+   * @returns {boolean}
    * @description Checks if an instance contains no items.
    */
-  isEmpty(){
+  isEmpty() {
     return this.#_items.isEmpty();
   }
 
   /**
-   * @param {none}
-   * @returns {bool}
+   * @returns {boolean}
    * @description Checks if an instance contains any items.
    */
-  isNotEmpty(){
+  isNotEmpty() {
     return this.#_items.isNotEmpty();
   }
 
   /**
-   * @param {any}
-   * @returns {bool}
+   * @param {any} value - index value
+   * @returns {boolean}
    * @description Checks if a given value is a valid index and
    *              it fits an index range within an instance.
    */
-  chkIndex(value){
+  chkIndex(value) {
     return this.#_items.chkIndex(value);
   }
 
   /**
+   * @param {any} value - value to check
+   * @param {boolean} [opt=false] - defines a type of result
+   * @returns {(boolean|number)}
    * @see TItemsListEx.chkIndexEx
    * @description Checks if a given value is a valid index and
    *              it fits an index range within an instance.
    */
-  chkIndexEx(...args){
+  chkIndexEx(...args) {
     return this.#_items.chkIndexEx(...args);
   }
 
   /**
-   * @param {HTMLElement}
-   * @returns {index}
+   * @param {HTMLElement} item  - element to search
+   * @returns {number}
    * @description Returns an index of a given element.
    */
-  srchIndex(item){
+  srchIndex(item) {
     return isHTMLElement(item) ? this.#_items.srchIndex(item) : -1;
   }
 
   /**
-   * @param {ID_STRING}
-   * @param {any}
-   * @returns {index}
+   * @param {string} name - attribute name
+   * @param {any} [value=""] - attribute value
+   * @returns {number}
    * @description Returns an index of an element wich has an attribute
    *              with a given name and value.
    */
-  srchIndexByAttr(name, value = ''){
+  srchIndexByAttr(name, value = '') {
     const _name = typeof name === 'string' ? name.trim() : '';
     const { index } = srchListElementByAttr(this.#_items, _name, value);
     return index;
   };
 
   /**
-   * @param {ID_STRING}
-   * @returns {index}
+   * @param {string} value - element ID
+   * @returns {number}
    * @description Returns an index of an element wich has a given ID.
    */
-  srchIndexByID(value){
+  srchIndexByID(value) {
     const { index } = srchListElementByAttr(this.#_items, 'id', value);
     return index;
   };
 
   /**
-   * @param {index}
-   * @returns {bool}
+   * @param {(number|string)} index - element index
+   * @returns {boolean}
    * @description Sets a current index.
    */
-  setCurIndex(index){
+  setCurIndex(index) {
     const isSUCCEED = this.#_items.setIndex(index);
     if (isSUCCEED) {
       const markCurrentItem = this.#_options.markCurrentItem;
       const _status = this.#_status;
       if (markCurrentItem && _status.curIndex !== -1) {
-        unmarkCurrentHtmlElement(_status.curItem);
+        unmarkCurrentHTMLElement(_status.curItem);
       };
       const item = this.getItem(index);
       _status.curIndex = Number(index);
       _status.curItem = item;
-      if (markCurrentItem) markHtmlElementAsCurrent(item);
+      if (markCurrentItem) markHTMLElementAsCurrent(item);
     };
     return isSUCCEED;
   }
 
   /**
-   * @param {none}
-   * @returns {none}
+   * @returns {void}
    * @description Resets a current index.
    */
-  rstCurIndex(){
+  rstCurIndex() {
     const _status = this.#_status;
     if (this.#_options.markCurrentItem && _status.curIndex !== -1) {
-      unmarkCurrentHtmlElement(_status.curItem);
+      unmarkCurrentHTMLElement(_status.curItem);
     };
     this.#_items.rstIndex();
     _status.curIndex = this.#_items.curIndex;
@@ -299,46 +328,45 @@ class THtmlItemsListContainer {
   }
 
   /**
-   * @param {index}
+   * @param {(number|string)} index - element index
    * @returns {?HTMLElement}
    * @description Returns an item addressed by a given index.
    */
-  getItem(index){
+  getItem(index) {
     const item = this.#_items.getItem(index);
     return isHTMLElement(item) ? item : null;
   }
 
   /**
-   * @param {ID_STRING}
-   * @param {any}
+   * @param {string} name - attribute name
+   * @param {any} [value=""] - attribute value
    * @returns {?HTMLElement}
    * @description Returns an item wich has an attribute
    *              with a given name and value.
    */
-  getItemByAttr(name, value = ''){
+  getItemByAttr(name, value = '') {
     const _name = typeof name === 'string' ? name.trim() : '';
     const { item } = srchListElementByAttr(this.#_items, _name, value);
     return item;
   }
 
   /**
-   * @param {ID_STRING}
-   * @param {any}
+   * @param {string} value - element ID
    * @returns {?HTMLElement}
    * @description Returns an item wich has a given ID.
    */
-  getItemByID(value){
+  getItemByID(value) {
     const { item } = srchListElementByAttr(this.#_items, 'id', value);
     return item;
   }
 
   /**
-   * @param {HTMLElement}
-   * @param {bool} [opt=false]
-   * @returns {index}
+   * @param {HTMLElement} item
+   * @param {boolean} [opt=false]
+   * @returns {number}
    * @description Adds an item to an instance.
    */
-  addItem(item, opt){
+  addItem(item, opt) {
     const forceCI = typeof opt === 'boolean' ? opt : false;
     const index = (
       isHTMLElement(item)
@@ -348,7 +376,7 @@ class THtmlItemsListContainer {
     const isSUCCEED = index !== -1;
     if (isSUCCEED) {
       const { autoHideNewItems, itemBaseClassID } = this.#_options;
-      if (autoHideNewItems) hideHtmlElement(item);
+      if (autoHideNewItems) hideHTMLElement(item);
       if (itemBaseClassID.length > 0) item.classList.add(...itemBaseClassID);
       if (forceCI) this.setCurIndex(index);
       const _host = this.#_host;
@@ -358,13 +386,13 @@ class THtmlItemsListContainer {
   }
 
   /**
-   * @param {index}
+   * @param {(number|string)} index - element index
    * @param {any} [opt]
-   * @param {bool} [optEx=true]
-   * @returns {bool}
+   * @param {boolean} [optEx=true]
+   * @returns {boolean}
    * @description Deletes an item from an instance.
    */
-  delItem(index, opt, optEx){
+  delItem(index, opt, optEx) {
     const _items = this.#_items;
     const item = _items.delItemEx(index, opt);
     const isSUCCEED = item !== undefined;
@@ -384,48 +412,48 @@ class THtmlItemsListContainer {
   }
 
   /**
-   * @param {index}
-   * @param {bool} [opt=false]
-   * @returns {bool}
+   * @param {(number|string)} index - element index
+   * @param {boolean} [opt=false]
+   * @returns {boolean}
    * @description Selects an item addressed by a given index.
    */
-  selectItem(index, opt){
+  selectItem(index, opt) {
     const forceCI = typeof opt === 'boolean' ? opt : false;
-    const isSUCCEED = selectHtmlElement(this.#_items.getItem(index));
+    const isSUCCEED = selectHTMLElement(this.#_items.getItem(index));
     if (isSUCCEED && forceCI) this.setCurIndex(index);
     return isSUCCEED;
   }
 
   /**
-   * @param {index}
-   * @returns {bool}
+   * @param {(number|string)} index - element index
+   * @returns {boolean}
    * @description Unselects an item addressed by a given index.
    */
-  unselectItem(index){
-    return unselectHtmlElement(this.#_items.getItem(index));
+  unselectItem(index) {
+    return unselectHTMLElement(this.#_items.getItem(index));
   }
 
   /**
-   * @param {index}
-   * @returns {bool}
+   * @param {(number|string)} index - element index
+   * @returns {boolean}
    * @description Hides an item addressed by a given index.
    */
-  hideItem(index){
-    return hideHtmlElement(this.#_items.getItem(index));
+  hideItem(index) {
+    return hideHTMLElement(this.#_items.getItem(index));
   }
 
   /**
-   * @param {index}
-   * @returns {bool}
+   * @param {(number|string)} index - element index
+   * @returns {boolean}
    * @description Shows an item addressed by a given index.
    */
-  showItem(index){
-    return showHtmlElement(this.#_items.getItem(index));
+  showItem(index) {
+    return showHTMLElement(this.#_items.getItem(index));
   }
 
   /**
-   * @param {index}
-   * @returns {bool}
+   * @param {(number|string)} index - element index
+   * @returns {boolean}
    * @description Checks whether an item is selected.
    */
   isSelectedItem(index) {
@@ -433,8 +461,8 @@ class THtmlItemsListContainer {
   }
 
   /**
-   * @param {index}
-   * @returns {bool}
+   * @param {(number|string)} index - element index
+   * @returns {boolean}
    * @description Checks whether an item is hidden.
    */
   isHiddenItem(index) {
@@ -445,27 +473,46 @@ class THtmlItemsListContainer {
 
 /**
  * @augments THtmlItemsListContainer
- * @description This class enhanced a capabilities implemented
- *              in the `THtmlItemsListContainer` class
+ * @classdesc This class enhanced a capabilities implemented
+ *            in the `THtmlItemsListContainer` class
  */
 class THtmlItemsListController extends THtmlItemsListContainer {
-  #_host = null;
-  #_stubs = null;
-  #_selects = null;
-  #_options = null;
-  #_status = null;
-  #_events = null;
+  /** @property {?HTMLElement} */
+  #_host;
+  /** @property {THtmlStubItemsSet} */
+  #_stubs;
+  /** @property {Set} */
+  #_selects;
+  /** @property {object} */
+  #_options;// = null;
+  /**
+   * @typedef {Object} statILCtrl
+   * @property {boolean} isSelectionLocked
+   * @property {boolean} isStubItemShown
+   * @property {boolean} isHostEnabled
+   * @property {boolean} catchEventOnHost
+   * @property {boolean} execDelItem
+   * @property {number} execDelItemDI
+   * @property {number} execDelItemCI
+   * @inner
+   * @description A controler status
+   */
+  /** @property {statILCtrl} */
+  #_status;
+  /** @property {Map} */
+  #_events;
 
   /**
-   * @param {HTMLElement}
+   * @param {?HTMLElement} host
    * @param {object} [opt]
-   * @param {bool} [opt.autoHideNewItems=false]
-   * @param {bool} [opt.markCurrentItem=false]
-   * @param {(string|array)} [opt.itemBaseClassID]
-   * @param {bool} [opt.showStubsIfEmpty=false]
-   * @param {bool} [opt.allowGroupSelection=false]
-   * @param {bool} [opt.allowSelectionLocks=false]
+   * @param {boolean} [opt.autoHideNewItems=false]
+   * @param {boolean} [opt.markCurrentItem=false]
+   * @param {(string|string[])} [opt.itemBaseClassID]
+   * @param {boolean} [opt.showStubsIfEmpty=false]
+   * @param {boolean} [opt.allowGroupSelection=false]
+   * @param {boolean} [opt.allowSelectionLocks=false]
    * @param {object} [opt.stubs]
+   * @description Creates a new instance of the class.
    */
   constructor(host, opt) {
     // check host element
@@ -497,6 +544,7 @@ class THtmlItemsListController extends THtmlItemsListContainer {
     // save options
     this.#_options = _options;
     // init status flags set
+    /** @type {statILCtrl} */
     const _status = {
       isSelectionLocked: false,
       isStubItemShown: false,
@@ -525,8 +573,8 @@ class THtmlItemsListController extends THtmlItemsListContainer {
   }
 
   /**
-   * @param {object}
-   * @returns {none}
+   * @param {object} e
+   * @returns {void}
    * @private
    */
   #_on_will_select_item = (e) => {
@@ -579,9 +627,9 @@ class THtmlItemsListController extends THtmlItemsListContainer {
   };
 
   /**
-   * @param {ID_STRING}
-   * @param {...any}
-   * @returns {none}
+   * @param {string} name
+   * @param {...any} args
+   * @returns {void}
    * @private
    * @see triggerEventHandler
    */
@@ -590,10 +638,11 @@ class THtmlItemsListController extends THtmlItemsListContainer {
   };
 
   /**
-   * @property {array}
+   * @property {HTMLElement[]}
    * @readonly
+   * @description Returns a list of the selected elements
    */
-  get SelectedItems(){
+  get SelectedItems() {
     const _selects = this.#_selects;
     // // TODO: consider to use: `[...<value>]`
     let result = [];
@@ -606,26 +655,27 @@ class THtmlItemsListController extends THtmlItemsListContainer {
   /**
    * @property {THtmlStubItemsSet}
    * @readonly
+   * @description Returns a `THtmlStubItemsSet` instance
    */
-  get StubItems(){
+  get StubItems() {
     return this.#_stubs;
   }
 
   /**
-   * @property {bool}
+   * @property {boolean}
    * @readonly
+   * @description Indicates whether a selection is locked
    */
-  get isSelectionLocked(){
+  get isSelectionLocked() {
     return this.#_status.isSelectionLocked;
   }
 
   /**
-   * @param {none}
-   * @returns {none}
+   * @returns {void}
    * @fires THtmlItemsListController#list-clear
    * @description Clears an instance content.
    */
-  clear(){
+  clear() {
     // // TODO: clear event handler on elements if set
     super.clear();
     this.#_selects.clear();
@@ -635,45 +685,43 @@ class THtmlItemsListController extends THtmlItemsListContainer {
     };
     /**
      * @event THtmlItemsListController#list-clear
-     * @type {none}
+     * @type {void}
      */
     this.#_triggerEvent('list-clear');
   }
 
   /**
-   * @param {none}
-   * @returns {none}
+   * @returns {void}
    * @description Locks an element selection.
    */
-  lockItemsSelection(){
+  lockItemsSelection() {
     if (this.#_options.allowSelectionLocks) {
       this.#_status.isSelectionLocked = true;
     };
   }
 
   /**
-   * @param {none}
-   * @returns {none}
+   * @returns {void}
    * @description Unlocks an element selection.
    */
-  unlockItemsSelection(){
+  unlockItemsSelection() {
     this.#_status.isSelectionLocked = false;
   }
 
   /**
-   * @param {index}
-   * @returns {bool}
+   * @param {(number|string)} index - element index
+   * @returns {boolean}
    * @fires THtmlItemsListController#current-item-chosen
    * @private
    * @description Sets a current index.
    */
-  #_setCurIndex(index){
+  #_setCurIndex(index) {
     const isSUCCEED = super.setCurIndex(index);
     /**
      * @event THtmlItemsListController#current-item-chosen
-     * @type {object}
-     * @property {index} index
-     * @property {null} item
+     * @type {Object}
+     * @property {number} index - element index
+     * @property {?HTMLElement} item - element
      */
     if (isSUCCEED) this.#_triggerEvent('current-item-chosen', {
       index: Number(index),
@@ -683,20 +731,19 @@ class THtmlItemsListController extends THtmlItemsListContainer {
   };
 
   /**
-   * @param {index}
-   * @returns {bool}
+   * @param {(number|string)} index - element index
+   * @returns {boolean}
    * @description Sets a current index.
    */
-  setCurIndex(index){
+  setCurIndex(index) {
     return this.selectItem(index, true);
   }
 
   /**
-   * @param {none}
-   * @returns {none}
+   * @returns {void}
    * @description Resets a current index.
    */
-  rstCurIndex(){
+  rstCurIndex() {
     const {
       execDelItem,
       execDelItemDI,
@@ -713,13 +760,14 @@ class THtmlItemsListController extends THtmlItemsListContainer {
   }
 
   /**
-   * @param {HTMLElement}
-   * @returns {index}
+   * @param {HTMLElement} item
+   * @param {boolean} [opt=false]
+   * @returns {number}
    * @fires THtmlItemsListController#first-item-added
    * @fires THtmlItemsListController#item-added
    * @description Adds an element to an instance members.
    */
-  addItem(item, opt){
+  addItem(item, opt) {
     const index = super.addItem(item, false);
     if (index !== -1) {
       const { autoHideNewItems, showStubsIfEmpty } = this.#_options;
@@ -743,9 +791,9 @@ class THtmlItemsListController extends THtmlItemsListContainer {
           };
           /**
            * @event THtmlItemsListController#first-item-added
-           * @type {object}
-           * @property {index} index
-           * @property {?HTMLElement} item
+           * @type {Object}
+           * @property {number} index - element index
+           * @property {?HTMLElement} item - element
            */
           this.#_triggerEvent('first-item-added', {
             index: index,
@@ -754,9 +802,9 @@ class THtmlItemsListController extends THtmlItemsListContainer {
         };
         /**
          * @event THtmlItemsListController#item-added
-         * @type {object}
-         * @property {index} index
-         * @property {?HTMLElement} item
+         * @type {Object}
+         * @property {number} index - element index
+         * @property {?HTMLElement} item - element
          */
         this.#_triggerEvent('item-added', {
           index: index,
@@ -775,14 +823,14 @@ class THtmlItemsListController extends THtmlItemsListContainer {
   }
 
   /**
-   * @param {index}
+   * @param {(number|string)} index - element index
    * @param {any} [opt]
-   * @returns {bool}
+   * @returns {boolean}
    * @fires THtmlItemsListController#list-clear
    * @fires THtmlItemsListController#item-removed
    * @description Deletes an element from an instance members.
    */
-  delItem(index, opt){
+  delItem(index, opt) {
     const item = super.getItem(index);
     let isSUCCEED = item !== undefined;
     const _status = this.#_status;
@@ -811,9 +859,9 @@ class THtmlItemsListController extends THtmlItemsListContainer {
           this.#_selects.delete(item);
           /**
            * @event THtmlItemsListController#item-removed
-           * @type {object}
-           * @property {index} index
-           * @property {?HTMLElement} item
+           * @type {Object}
+           * @property {number} index - element index
+           * @property {?HTMLElement} item - element
            */
           this.#_triggerEvent('item-removed', {
             index: Number(index),
@@ -835,22 +883,22 @@ class THtmlItemsListController extends THtmlItemsListContainer {
   }
 
   /**
-   * @param {index}
-   * @returns {bool}
+   * @param {(number|string)} index - element index
+   * @returns {boolean}
    * @private
    * @fires THtmlItemsListController#item-selected
    * @description Selects an element.
    */
-  #_selectItem(index){
+  #_selectItem(index) {
     const item = super.getItem(index);
-    const isSUCCEED = selectHtmlElement(item);
+    const isSUCCEED = selectHTMLElement(item);
     if (isSUCCEED) {
       this.#_selects.add(item);
       /**
        * @event THtmlItemsListController#item-selected
-       * @type {object}
-       * @property {index} index
-       * @property {?HTMLElement} item
+       * @type {Object}
+       * @property {number} index - element index
+       * @property {?HTMLElement} item - element
        */
       this.#_triggerEvent('item-selected', {
         index: Number(index),
@@ -861,12 +909,12 @@ class THtmlItemsListController extends THtmlItemsListContainer {
   }
 
   /**
-   * @param {index}
+   * @param {?HTMLElement} item - element
    * @param {object} [opt]
-   * @param {bool} [opt.ctrlKey=false]
-   * @param {bool} [opt.shiftKey=false]
-   * @param {bool} [opt.forceCI=false]
-   * @returns {none}
+   * @param {boolean} [opt.ctrlKey=false]
+   * @param {boolean} [opt.shiftKey=false]
+   * @param {boolean} [opt.forceCI=false]
+   * @returns {void}
    * @private
    * @description Selects an element.
    */
@@ -923,12 +971,12 @@ class THtmlItemsListController extends THtmlItemsListContainer {
   }
 
   /**
-   * @param {index}
-   * @param {bool} [opt=false]
-   * @returns {bool}
+   * @param {(number|string)} index - element index
+   * @param {boolean} [opt=false]
+   * @returns {boolean}
    * @description Selects an element.
    */
-  selectItem(index, opt){
+  selectItem(index, opt) {
     const item = super.getItem(index);
     let isSUCCEED = isHTMLElement(item);
     if (isSUCCEED) {
@@ -943,21 +991,21 @@ class THtmlItemsListController extends THtmlItemsListContainer {
   }
 
   /**
-   * @param {index}
-   * @returns {bool}
+   * @param {(number|string)} index - element index
+   * @returns {boolean}
    * @fires THtmlItemsListController#item-unselected
    * @description Unselects an element.
    */
-  unselectItem(index){
+  unselectItem(index) {
     const item = super.getItem(index);
-    let isSUCCEED = unselectHtmlElement(item);
+    let isSUCCEED = unselectHTMLElement(item);
     if (isSUCCEED) {
       this.#_selects.delete(item);
       /**
        * @event THtmlItemsListController#item-unselected
-       * @type {object}
-       * @property {index} index
-       * @property {?HTMLElement} item
+       * @type {Object}
+       * @property {number} index - element index
+       * @property {?HTMLElement} item - element
        */
       this.#_triggerEvent('item-unselected', {
         index: Number(index),
@@ -968,20 +1016,20 @@ class THtmlItemsListController extends THtmlItemsListContainer {
   }
 
   /**
-   * @param {index}
-   * @returns {bool}
+   * @param {(number|string)} index - element index
+   * @returns {boolean}
    * @fires THtmlItemsListController#item-hidden
    * @description Hides an element.
    */
-  hideItem(index){
+  hideItem(index) {
     const item = super.getItem(index);
-    let isSUCCEED = hideHtmlElement(item);
+    let isSUCCEED = hideHTMLElement(item);
     if (isSUCCEED) {
       /**
        * @event THtmlItemsListController#item-hidden
-       * @type {object}
-       * @property {index} index
-       * @property {?HTMLElement} item
+       * @type {Object}
+       * @property {number} index - element index
+       * @property {?HTMLElement} item - element
        */
       this.#_triggerEvent('item-hidden', {
         index: Number(index),
@@ -992,20 +1040,20 @@ class THtmlItemsListController extends THtmlItemsListContainer {
   }
 
   /**
-   * @param {index}
-   * @returns {bool}
+   * @param {(number|string)} index - element index
+   * @returns {boolean}
    * @fires THtmlItemsListController#item-shown
    * @description Shows an element.
    */
-  showItem(index){
+  showItem(index) {
     const item = super.getItem(index);
-    let isSUCCEED = showHtmlElement(item);
+    let isSUCCEED = showHTMLElement(item);
     if (isSUCCEED) {
       /**
        * @event THtmlItemsListController#item-shown
-       * @type {object}
-       * @property {index} index
-       * @property {?HTMLElement} item
+       * @type {Object}
+       * @property {number} index - element index
+       * @property {?HTMLElement} item - element
        */
       this.#_triggerEvent('item-shown', {
         index: Number(index),
@@ -1016,12 +1064,12 @@ class THtmlItemsListController extends THtmlItemsListContainer {
   }
 
   /**
-   * @param {ID_STRING}
-   * @param {func}
-   * @returns {none}
+   * @param {string} name - event name
+   * @param {func} evnt
+   * @returns {void}
    * @description Sets a callback function to handle event.
    */
-  on(name, evnt){
+  on(name, evnt) {
     pushEventHandler(this.#_events, name, evnt);
   }