@cntwg/html-helper 0.0.25 → 0.0.27

package/lib/html-ctrls/list.js

@@ -1,4 +1,4 @@
-// [v0.1.069-20250416]
+// [v0.1.072-20250827]
 
 // === module init block ===
 
@@ -35,17 +35,16 @@ const {
   //CSS_CLASS_ACTIVE,
 } = CSS_CLASS_STRING;
 
-// === module extra block (helper functions) ===
+// === module inner block ===
 
 /**
+ * Searches an element in a list by a given attributes of that element.
  * @function srchListElementByAttr
  * @param {TItemsListEx} list
- * @param {string} name
- * @param {string} [value=""]
+ * @param {string} name - target attribute name
+ * @param {string} [value=""] - target attribute 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);
@@ -90,11 +89,11 @@ const ILC_SMODE_CTRL = 2;
  */
 
 /**
+ * An options set for `THtmlItemsListContainer`-class
  * @typedef {Object} OPT_hlconsett
- * @property {boolean} [autoHideNewItems=false]
- * @property {boolean} [markCurrentItem=false]
+ * @property {boolean} [autoHideNewItems=false] - indicates whether to hide a new element
+ * @property {boolean} [markCurrentItem=false] - indicates whether to mark a current element
  * @property {(string|string[])} [itemBaseClassID]
- * @description An options set for `THtmlItemsListContainer`-class
  */
 
 /**
@@ -108,19 +107,19 @@ class THtmlItemsListContainer {
   /** @type {OPT_hlconsett} */
   #_options;// = null;
   /**
+   * A container status
    * @typedef {Object} statILCont
    * @property {number} curIndex
    * @property {?HTMLElement} curItem
    * @inner
-   * @description A container status
    */
   /** @type {statILCont} */
   #_status;
 
   /**
-   * @param {HTMLElement} host
+   * Creates an instance of a list container
+   * @param {HTMLElement} host - host element
    * @param {OPT_hlconsett} [opt] - options
-   * @description Creates an instance of a list container
    */
   constructor(host, opt) {
     // check host
@@ -220,8 +219,8 @@ class THtmlItemsListContainer {
   }
 
   /**
+   * Clears an instance content.
    * @returns {void}
-   * @description Clears an instance content.
    */
   clear() {
     this.#_items.clear();
@@ -233,58 +232,58 @@ class THtmlItemsListContainer {
   }
 
   /**
+   * Checks if an instance contains no items.
    * @returns {boolean}
-   * @description Checks if an instance contains no items.
    */
   isEmpty() {
     return this.#_items.isEmpty();
   }
 
   /**
+   * Checks if an instance contains any items.
    * @returns {boolean}
-   * @description Checks if an instance contains any items.
    */
   isNotEmpty() {
     return this.#_items.isNotEmpty();
   }
 
   /**
+   * Checks if a given value is a valid index and
+   * it fits an index range within an instance.
    * @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) {
     return this.#_items.chkIndex(value);
   }
 
   /**
+   * Checks if a given value is a valid index and
+   * it fits an index range within an instance.
    * @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) {
     return this.#_items.chkIndexEx(...args);
   }
 
   /**
+   * Returns an index of a given element.
    * @param {HTMLElement} item  - element to search
    * @returns {number}
-   * @description Returns an index of a given element.
    */
   srchIndex(item) {
     return isHTMLElement(item) ? this.#_items.srchIndex(item) : -1;
   }
 
   /**
+   * Returns an index of an element wich has an attribute
+   * with a given name and value.
    * @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 = '') {
     const _name = typeof name === 'string' ? name.trim() : '';
@@ -293,9 +292,9 @@ class THtmlItemsListContainer {
   };
 
   /**
+   * Returns an index of an element wich has a given ID.
    * @param {string} value - element ID
    * @returns {number}
-   * @description Returns an index of an element wich has a given ID.
    */
   srchIndexByID(value) {
     const { index } = srchListElementByAttr(this.#_items, 'id', value);
@@ -303,9 +302,9 @@ class THtmlItemsListContainer {
   };
 
   /**
+   * Sets a current index.
    * @param {(number|string)} index - element index
    * @returns {boolean}
-   * @description Sets a current index.
    */
   setCurIndex(index) {
     const isSUCCEED = this.#_items.setIndex(index);
@@ -324,8 +323,8 @@ class THtmlItemsListContainer {
   }
 
   /**
+   * Resets a current index.
    * @returns {void}
-   * @description Resets a current index.
    */
   rstCurIndex() {
     const _status = this.#_status;
@@ -338,9 +337,9 @@ class THtmlItemsListContainer {
   }
 
   /**
+   * Returns an item addressed by a given index.
    * @param {(number|string)} index - element index
    * @returns {?HTMLElement}
-   * @description Returns an item addressed by a given index.
    */
   getItem(index) {
     const item = this.#_items.getItem(index);
@@ -348,11 +347,10 @@ class THtmlItemsListContainer {
   }
 
   /**
+   * Returns an item wich has an attribute with a given name and value.
    * @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 = '') {
     const _name = typeof name === 'string' ? name.trim() : '';
@@ -361,9 +359,9 @@ class THtmlItemsListContainer {
   }
 
   /**
+   * Returns an item wich has a given ID.
    * @param {string} value - element ID
    * @returns {?HTMLElement}
-   * @description Returns an item wich has a given ID.
    */
   getItemByID(value) {
     const { item } = srchListElementByAttr(this.#_items, 'id', value);
@@ -371,10 +369,10 @@ class THtmlItemsListContainer {
   }
 
   /**
+   * Adds an item to an instance.
    * @param {HTMLElement} item
    * @param {boolean} [opt=false]
    * @returns {number}
-   * @description Adds an item to an instance.
    */
   addItem(item, opt) {
     const forceCI = typeof opt === 'boolean' ? opt : false;
@@ -396,11 +394,11 @@ class THtmlItemsListContainer {
   }
 
   /**
+   * Deletes an item from an instance.
    * @param {(number|string)} index - element index
    * @param {any} [opt]
    * @param {boolean} [optEx=true]
    * @returns {boolean}
-   * @description Deletes an item from an instance.
    */
   delItem(index, opt, optEx) {
     const _items = this.#_items;
@@ -422,10 +420,10 @@ class THtmlItemsListContainer {
   }
 
   /**
+   * Selects an item addressed by a given index.
    * @param {(number|string)} index - element index
    * @param {boolean} [opt=false]
    * @returns {boolean}
-   * @description Selects an item addressed by a given index.
    */
   selectItem(index, opt) {
     const forceCI = typeof opt === 'boolean' ? opt : false;
@@ -435,45 +433,45 @@ class THtmlItemsListContainer {
   }
 
   /**
+   * Unselects an item addressed by a given index.
    * @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));
   }
 
   /**
+   * Hides an item addressed by a given index.
    * @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));
   }
 
   /**
+   * Shows an item addressed by a given index.
    * @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));
   }
 
   /**
+   * Checks whether an item is selected.
    * @param {(number|string)} index - element index
    * @returns {boolean}
-   * @description Checks whether an item is selected.
    */
   isSelectedItem(index) {
     return isSelectedHTMLElement(this.#_items.getItem(index));
   }
 
   /**
+   * Checks whether an item is hidden.
    * @param {(number|string)} index - element index
    * @returns {boolean}
-   * @description Checks whether an item is hidden.
    */
   isHiddenItem(index) {
     return isHiddenHTMLElement(this.#_items.getItem(index));
@@ -483,13 +481,15 @@ class THtmlItemsListContainer {
 
 /**
  * @typedef {Object} OPT_hlctlsett
- * @property {boolean} [autoHideNewItems=false]
- * @property {boolean} [markCurrentItem=false]
+ * @property {boolean} [autoHideNewItems=false] - indicates whether to hide a new element
+ * @property {boolean} [markCurrentItem=false] - indicates whether to mark a current element
  * @property {(string|string[])} [itemBaseClassID]
- * @property {boolean} [showStubsIfEmpty=false]
- * @property {boolean} [allowGroupSelection=false]
- * @property {boolean} [allowSelectionLocks=false]
- * @property {object} [stubs]
+ * @property {boolean} [showStubsIfEmpty=false] - indicates whether to show stubs if empty
+ * @property {boolean} [allowGroupSelection=false] - indicates whether
+ *    a selection of the elements group is allowed
+ * @property {boolean} [allowSelectionLocks=false] - indicates whether locking
+ *    of an element selection is allowed
+ * @property {OPT_stubconsett} [stubs]
  * @description An options set for `THtmlItemsListController`-class
  */
 
@@ -508,6 +508,7 @@ class THtmlItemsListController extends THtmlItemsListContainer {
   /** @property {OPT_hlctlsett} */
   #_options;// = null;
   /**
+   * A controler status
    * @typedef {Object} statILCtrl
    * @property {boolean} isSelectionLocked
    * @property {boolean} isStubItemShown
@@ -517,7 +518,6 @@ class THtmlItemsListController extends THtmlItemsListContainer {
    * @property {number} execDelItemDI
    * @property {number} execDelItemCI
    * @inner
-   * @description A controler status
    */
   /** @property {statILCtrl} */
   #_status;
@@ -525,15 +525,16 @@ class THtmlItemsListController extends THtmlItemsListContainer {
   #_events;
 
   /**
-   * @param {?HTMLElement} host
-   * @param {OPT_hlctlsett} [opt]
-   * @description Creates a new instance of the class.
+   * Creates a new instance of the class.
+   * @param {?HTMLElement} host - host element
+   * @param {OPT_hlctlsett} [opt] - options
    */
   constructor(host, opt) {
     // check host element
     const isHostEnabled = isHTMLElement(host);
     const _host = isHostEnabled ? host : null;
     // check options
+    /** @type {OPT_hlctlsett} */
     const _options = isPlainObject(opt) ? opt : {};
     // call parent constructor
     super(_host, _options);
@@ -588,7 +589,7 @@ class THtmlItemsListController extends THtmlItemsListContainer {
   }
 
   /**
-   * @param {object} e
+   * @param {object} e - event
    * @returns {void}
    * @private
    */
@@ -605,8 +606,8 @@ class THtmlItemsListController extends THtmlItemsListContainer {
     //console.log('CHECK: e => ditail:['+e.detail+']');
     //console.log('CHECK: e => phase:['+eventPhase+']');
     const onClickNum = readAsNumber(e.detail, 0);
-    const _status = this.#_status;
-    const { isSelectionLocked, catchEventOnHost } = _status;
+    const host = this.#_host;
+    const { isSelectionLocked, catchEventOnHost } = this.#_status;
     let curItem = null;
     switch (eventPhase) {
       //* // NOTE: currently on eventPhase = 2 and 3
@@ -614,7 +615,7 @@ class THtmlItemsListController extends THtmlItemsListContainer {
         /**/// capturing stage
       case 2: {
         /**/// target stage
-        if (target !== this.#_host) curItem = target;
+        if (target !== host) curItem = target;
         break;
       }
       case 3: {
@@ -622,9 +623,7 @@ class THtmlItemsListController extends THtmlItemsListContainer {
         curItem = catchEventOnHost ? target : currentTarget;
         break;
       }
-      default: {
-        break;
-      }
+      default: {}
     };
     if (
       !isSelectionLocked
@@ -632,7 +631,19 @@ class THtmlItemsListController extends THtmlItemsListContainer {
       && (onClickNum === 0 || onClickNum === 1)
       && !curItem.classList.contains(CSS_CLASS_DISABLED)
     ) {
-      //console.log('CHECK: e => tag:['+curItem.tagName+']');
+      //console.log(`CHECK: e => tag:[${curItem.tagName}]`);
+      if (host) {
+        // find an actual list element in case when some inner element was clicking
+        let tmpItem = curItem;
+        while (tmpItem) {
+          //console.log(`CHECK: e => target.tag:[${tmpItem.tagName}]`);
+          tmpItem = tmpItem.parentElement;
+          //console.log(`CHECK: e => next.tag:[${tmpItem.tagName}]`);
+          if (tmpItem === host) break;
+          if (tmpItem) curItem = tmpItem;
+        };
+      };
+      //console.log(`CHECK: e => tag:[${curItem.tagName}]`);
       this.#_selectItemEx(curItem, {
         ctrlKey: ctrlKey,
         shiftKey: shiftKey,
@@ -642,7 +653,7 @@ class THtmlItemsListController extends THtmlItemsListContainer {
   };
 
   /**
-   * @param {string} name
+   * @param {string} name - event name
    * @param {...any} args
    * @returns {void}
    * @private
@@ -686,9 +697,9 @@ class THtmlItemsListController extends THtmlItemsListContainer {
   }
 
   /**
+   * Clears an instance content.
    * @returns {void}
    * @fires THtmlItemsListController#list-clear
-   * @description Clears an instance content.
    */
   clear() {
     // // TODO: clear event handler on elements if set
@@ -706,8 +717,8 @@ class THtmlItemsListController extends THtmlItemsListContainer {
   }
 
   /**
+   * Locks an element selection.
    * @returns {void}
-   * @description Locks an element selection.
    */
   lockItemsSelection() {
     if (this.#_options.allowSelectionLocks) {
@@ -716,19 +727,19 @@ class THtmlItemsListController extends THtmlItemsListContainer {
   }
 
   /**
+   * Unlocks an element selection.
    * @returns {void}
-   * @description Unlocks an element selection.
    */
   unlockItemsSelection() {
     this.#_status.isSelectionLocked = false;
   }
 
   /**
+   * Sets a current index.
    * @param {(number|string)} index - element index
    * @returns {boolean}
    * @fires THtmlItemsListController#current-item-chosen
    * @private
-   * @description Sets a current index.
    */
   #_setCurIndex(index) {
     const isSUCCEED = super.setCurIndex(index);
@@ -746,17 +757,17 @@ class THtmlItemsListController extends THtmlItemsListContainer {
   };
 
   /**
+   * Sets a current index.
    * @param {(number|string)} index - element index
    * @returns {boolean}
-   * @description Sets a current index.
    */
   setCurIndex(index) {
     return this.selectItem(index, true);
   }
 
   /**
+   * Resets a current index.
    * @returns {void}
-   * @description Resets a current index.
    */
   rstCurIndex() {
     const {
@@ -775,12 +786,12 @@ class THtmlItemsListController extends THtmlItemsListContainer {
   }
 
   /**
-   * @param {HTMLElement} item
+   * Adds an element to an instance members.
+   * @param {HTMLElement} item - some element
    * @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) {
     const index = super.addItem(item, false);
@@ -838,12 +849,12 @@ class THtmlItemsListController extends THtmlItemsListContainer {
   }
 
   /**
+   * Deletes an element from an instance members.
    * @param {(number|string)} index - element index
    * @param {any} [opt]
    * @returns {boolean}
    * @fires THtmlItemsListController#list-clear
    * @fires THtmlItemsListController#item-removed
-   * @description Deletes an element from an instance members.
    */
   delItem(index, opt) {
     const item = super.getItem(index);
@@ -898,11 +909,11 @@ class THtmlItemsListController extends THtmlItemsListContainer {
   }
 
   /**
+   * Selects an element.
    * @param {(number|string)} index - element index
    * @returns {boolean}
    * @private
    * @fires THtmlItemsListController#item-selected
-   * @description Selects an element.
    */
   #_selectItem(index) {
     const item = super.getItem(index);
@@ -924,6 +935,7 @@ class THtmlItemsListController extends THtmlItemsListContainer {
   }
 
   /**
+   * Selects an element.
    * @param {?HTMLElement} item - element
    * @param {object} [opt]
    * @param {boolean} [opt.ctrlKey=false]
@@ -931,7 +943,6 @@ class THtmlItemsListController extends THtmlItemsListContainer {
    * @param {boolean} [opt.forceCI=false]
    * @returns {void}
    * @private
-   * @description Selects an element.
    */
   #_selectItemEx(item, opt){
     const _selects = this.#_selects;
@@ -986,10 +997,10 @@ class THtmlItemsListController extends THtmlItemsListContainer {
   }
 
   /**
+   * Selects an element.
    * @param {(number|string)} index - element index
    * @param {boolean} [opt=false]
    * @returns {boolean}
-   * @description Selects an element.
    */
   selectItem(index, opt) {
     const item = super.getItem(index);
@@ -1006,10 +1017,10 @@ class THtmlItemsListController extends THtmlItemsListContainer {
   }
 
   /**
+   * Unselects an element.
    * @param {(number|string)} index - element index
    * @returns {boolean}
    * @fires THtmlItemsListController#item-unselected
-   * @description Unselects an element.
    */
   unselectItem(index) {
     const item = super.getItem(index);
@@ -1031,10 +1042,10 @@ class THtmlItemsListController extends THtmlItemsListContainer {
   }
 
   /**
+   * Hides an element.
    * @param {(number|string)} index - element index
    * @returns {boolean}
    * @fires THtmlItemsListController#item-hidden
-   * @description Hides an element.
    */
   hideItem(index) {
     const item = super.getItem(index);
@@ -1055,10 +1066,10 @@ class THtmlItemsListController extends THtmlItemsListContainer {
   }
 
   /**
+   * Shows an element.
    * @param {(number|string)} index - element index
    * @returns {boolean}
    * @fires THtmlItemsListController#item-shown
-   * @description Shows an element.
    */
   showItem(index) {
     const item = super.getItem(index);
@@ -1079,10 +1090,10 @@ class THtmlItemsListController extends THtmlItemsListContainer {
   }
 
   /**
+   * Sets a callback function to handle event.
    * @param {string} name - event name
    * @param {func} evnt
    * @returns {void}
-   * @description Sets a callback function to handle event.
    */
   on(name, evnt) {
     pushEventHandler(this.#_events, name, evnt);