@cntwg/html-helper 0.0.20 → 0.0.22

package/lib/html-ctrls/list.js

@@ -1,4 +1,4 @@
-// [v0.1.060-20230408]
+// [v0.1.063-20240714]
 
 // === module init block ===
 
@@ -37,6 +37,16 @@ const ILC_SMODE_CTRL = 2;
 
 // === module extra block (helper functions) ===
 
+/**
+ * @function srchListElementByAttr
+ * @param {TItemsListEx}
+ * @param {string}
+ * @param {string}
+ * @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;
@@ -61,16 +71,36 @@ function srchListElementByAttr(list, name, value = '') {
   return isACCEPTED ? { index, item } : { index, item: null };
 };
 
-// === module main block (function definitions) ===
+// === module main block ===
 
-// === module main block (class definitions) ===
+/***
+ * (* constant definitions *)
+ */
 
+/***
+ * (* function definitions *)
+ */
+
+/***
+ * (* class definitions *)
+ */
+
+/**
+ * @description This class implements an instance of a list container
+ */
 class THtmlItemsListContainer {
   #_host = null;
   #_items = null;
   #_options = null;
   #_status = null;
 
+  /**
+   * @param {HTMLElement}
+   * @param {object} [opt]
+   * @param {bool} [opt.autoHideNewItems=false]
+   * @param {bool} [opt.markCurrentItem=false]
+   * @param {(string|array)} [opt.itemBaseClassID]
+   */
   constructor(host, opt) {
     // check host
     this.#_host = isHTMLElement(host) ? host : null;
@@ -102,35 +132,68 @@ class THtmlItemsListContainer {
     this.#_options = _options;
   }
 
+  /**
+   * @property {number}
+   * @readonly
+   */
   get count(){
     return this.#_items.count;
   }
 
+  /**
+   * @property {index}
+   * @readonly
+   */
   get curIndex(){
     return this.#_items.curIndex;
   }
 
+  /**
+   * @property {index}
+   * @readonly
+   */
   get minIndex(){
     return this.#_items.minIndex;
   }
 
+  /**
+   * @property {index}
+   * @readonly
+   */
   get maxIndex(){
     return this.#_items.maxIndex;
   }
 
+  /**
+   * @property {index}
+   * @readonly
+   */
   get prevIndex(){
     return this.#_items.prevIndex;
   }
 
+  /**
+   * @property {index}
+   * @readonly
+   */
   get nextIndex(){
     return this.#_items.nextIndex;
   }
 
+  /**
+   * @property {?HTMLElement}
+   * @readonly
+   */
   get curItem(){
     const item = this.#_items.curItem;
     return isHTMLElement(item) ? item : null;
   }
 
+  /**
+   * @param {none}
+   * @returns {none}
+   * @description Clears an instance content.
+   */
   clear(){
     this.#_items.clear();
     const _status = this.#_status;
@@ -140,37 +203,80 @@ class THtmlItemsListContainer {
     if (_host) _host.innerHTML = '';
   }
 
+  /**
+   * @param {none}
+   * @returns {bool}
+   * @description Checks if an instance contains no items.
+   */
   isEmpty(){
     return this.#_items.isEmpty();
   }
 
+  /**
+   * @param {none}
+   * @returns {bool}
+   * @description Checks if an instance contains any items.
+   */
   isNotEmpty(){
     return this.#_items.isNotEmpty();
   }
 
+  /**
+   * @param {any}
+   * @returns {bool}
+   * @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);
   }
 
+  /**
+   * @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);
   }
 
+  /**
+   * @param {HTMLElement}
+   * @returns {index}
+   * @description Returns an index of a given element.
+   */
   srchIndex(item){
     return isHTMLElement(item) ? this.#_items.srchIndex(item) : -1;
   }
 
+  /**
+   * @param {ID_STRING}
+   * @param {any}
+   * @returns {index}
+   * @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() : '';
     const { index } = srchListElementByAttr(this.#_items, _name, value);
     return index;
   };
 
+  /**
+   * @param {ID_STRING}
+   * @returns {index}
+   * @description Returns an index of an element wich has a given ID.
+   */
   srchIndexByID(value){
     const { index } = srchListElementByAttr(this.#_items, 'id', value);
     return index;
   };
 
+  /**
+   * @param {index}
+   * @returns {bool}
+   * @description Sets a current index.
+   */
   setCurIndex(index){
     const isSUCCEED = this.#_items.setIndex(index);
     if (isSUCCEED) {
@@ -187,6 +293,11 @@ class THtmlItemsListContainer {
     return isSUCCEED;
   }
 
+  /**
+   * @param {none}
+   * @returns {none}
+   * @description Resets a current index.
+   */
   rstCurIndex(){
     const _status = this.#_status;
     if (this.#_options.markCurrentItem && _status.curIndex !== -1) {
@@ -197,22 +308,46 @@ class THtmlItemsListContainer {
     _status.curItem = this.curItem;
   }
 
+  /**
+   * @param {index}
+   * @returns {?HTMLElement}
+   * @description Returns an item addressed by a given index.
+   */
   getItem(index){
     const item = this.#_items.getItem(index);
     return isHTMLElement(item) ? item : null;
   }
 
+  /**
+   * @param {ID_STRING}
+   * @param {any}
+   * @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() : '';
     const { item } = srchListElementByAttr(this.#_items, _name, value);
     return item;
   }
 
+  /**
+   * @param {ID_STRING}
+   * @param {any}
+   * @returns {?HTMLElement}
+   * @description Returns an item wich has a given ID.
+   */
   getItemByID(value){
     const { item } = srchListElementByAttr(this.#_items, 'id', value);
     return item;
   }
 
+  /**
+   * @param {HTMLElement}
+   * @param {bool} [opt=false]
+   * @returns {index}
+   * @description Adds an item to an instance.
+   */
   addItem(item, opt){
     const forceCI = typeof opt === 'boolean' ? opt : false;
     const index = (
@@ -232,6 +367,13 @@ class THtmlItemsListContainer {
     return isSUCCEED ? index : -1;
   }
 
+  /**
+   * @param {index}
+   * @param {any} [opt]
+   * @param {bool} [optEx=true]
+   * @returns {bool}
+   * @description Deletes an item from an instance.
+   */
   delItem(index, opt, optEx){
     const _items = this.#_items;
     const item = _items.delItemEx(index, opt);
@@ -251,6 +393,12 @@ class THtmlItemsListContainer {
     return isSUCCEED;
   }
 
+  /**
+   * @param {index}
+   * @param {bool} [opt=false]
+   * @returns {bool}
+   * @description Selects an item addressed by a given index.
+   */
   selectItem(index, opt){
     const forceCI = typeof opt === 'boolean' ? opt : false;
     const isSUCCEED = selectHtmlElement(this.#_items.getItem(index));
@@ -258,28 +406,58 @@ class THtmlItemsListContainer {
     return isSUCCEED;
   }
 
+  /**
+   * @param {index}
+   * @returns {bool}
+   * @description Unselects an item addressed by a given index.
+   */
   unselectItem(index){
     return unselectHtmlElement(this.#_items.getItem(index));
   }
 
+  /**
+   * @param {index}
+   * @returns {bool}
+   * @description Hides an item addressed by a given index.
+   */
   hideItem(index){
     return hideHtmlElement(this.#_items.getItem(index));
   }
 
+  /**
+   * @param {index}
+   * @returns {bool}
+   * @description Shows an item addressed by a given index.
+   */
   showItem(index){
     return showHtmlElement(this.#_items.getItem(index));
   }
 
+  /**
+   * @param {index}
+   * @returns {bool}
+   * @description Checks whether an item is selected.
+   */
   isSelectedItem(index) {
     return isSelectedHTMLElement(this.#_items.getItem(index));
   }
 
+  /**
+   * @param {index}
+   * @returns {bool}
+   * @description Checks whether an item is hidden.
+   */
   isHiddenItem(index) {
     return isHiddenHTMLElement(this.#_items.getItem(index));
   }
 
 };
 
+/**
+ * @augments THtmlItemsListContainer
+ * @description This class enhanced a capabilities implemented
+ *              in the `THtmlItemsListContainer` class
+ */
 class THtmlItemsListController extends THtmlItemsListContainer {
   #_host = null;
   #_stubs = null;
@@ -288,6 +466,17 @@ class THtmlItemsListController extends THtmlItemsListContainer {
   #_status = null;
   #_events = null;
 
+  /**
+   * @param {HTMLElement}
+   * @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 {object} [opt.stubs]
+   */
   constructor(host, opt) {
     // check host element
     const isHostEnabled = isHTMLElement(host);
@@ -345,6 +534,11 @@ class THtmlItemsListController extends THtmlItemsListContainer {
     this.#_status = _status;
   }
 
+  /**
+   * @param {object}
+   * @returns {none}
+   * @private
+   */
   #_on_will_select_item = (e) => {
     //console.log('THtmlItemsListController._on_will_select_item() ==> was called...');
     //e.preventDefault(); /* need to reconsider reason for use */
@@ -394,10 +588,21 @@ class THtmlItemsListController extends THtmlItemsListContainer {
     };
   };
 
+  /**
+   * @param {ID_STRING}
+   * @param {...any}
+   * @returns {none}
+   * @private
+   * @see triggerEventHandler
+   */
   #_triggerEvent = (name, ...args) => {
     triggerEventHandler(this.#_events, name, ...args);
   };
 
+  /**
+   * @property {array}
+   * @readonly
+   */
   get SelectedItems(){
     const _selects = this.#_selects;
     // // TODO: consider to use: `[...<value>]`
@@ -408,14 +613,28 @@ class THtmlItemsListController extends THtmlItemsListContainer {
     return result;
   }
 
+  /**
+   * @property {THtmlStubItemsSet}
+   * @readonly
+   */
   get StubItems(){
     return this.#_stubs;
   }
 
+  /**
+   * @property {bool}
+   * @readonly
+   */
   get isSelectionLocked(){
     return this.#_status.isSelectionLocked;
   }
 
+  /**
+   * @param {none}
+   * @returns {none}
+   * @fires THtmlItemsListController#list-clear
+   * @description Clears an instance content.
+   */
   clear(){
     // // TODO: clear event handler on elements if set
     super.clear();
@@ -424,21 +643,48 @@ class THtmlItemsListController extends THtmlItemsListContainer {
       // show default stub-item
       this.#_status.isStubItemShown = this.#_stubs.showDefItem();
     };
+    /**
+     * @event THtmlItemsListController#list-clear
+     * @type {none}
+     */
     this.#_triggerEvent('list-clear');
   }
 
+  /**
+   * @param {none}
+   * @returns {none}
+   * @description Locks an element selection.
+   */
   lockItemsSelection(){
     if (this.#_options.allowSelectionLocks) {
       this.#_status.isSelectionLocked = true;
     };
   }
 
+  /**
+   * @param {none}
+   * @returns {none}
+   * @description Unlocks an element selection.
+   */
   unlockItemsSelection(){
     this.#_status.isSelectionLocked = false;
   }
 
+  /**
+   * @param {index}
+   * @returns {bool}
+   * @fires THtmlItemsListController#current-item-chosen
+   * @private
+   * @description Sets a current index.
+   */
   #_setCurIndex(index){
     const isSUCCEED = super.setCurIndex(index);
+    /**
+     * @event THtmlItemsListController#current-item-chosen
+     * @type {object}
+     * @property {index} index
+     * @property {null} item
+     */
     if (isSUCCEED) this.#_triggerEvent('current-item-chosen', {
       index: Number(index),
       item: null,
@@ -446,10 +692,20 @@ class THtmlItemsListController extends THtmlItemsListContainer {
     return isSUCCEED;
   };
 
+  /**
+   * @param {index}
+   * @returns {bool}
+   * @description Sets a current index.
+   */
   setCurIndex(index){
     return this.selectItem(index, true);
   }
 
+  /**
+   * @param {none}
+   * @returns {none}
+   * @description Resets a current index.
+   */
   rstCurIndex(){
     const {
       execDelItem,
@@ -466,6 +722,13 @@ class THtmlItemsListController extends THtmlItemsListContainer {
     super.rstCurIndex();
   }
 
+  /**
+   * @param {HTMLElement}
+   * @returns {index}
+   * @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);
     if (index !== -1) {
@@ -488,11 +751,23 @@ class THtmlItemsListController extends THtmlItemsListContainer {
             // hide default stub-item
             _status.isStubItemShown = false;
           };
+          /**
+           * @event THtmlItemsListController#first-item-added
+           * @type {object}
+           * @property {index} index
+           * @property {?HTMLElement} item
+           */
           this.#_triggerEvent('first-item-added', {
             index: index,
             item: item,
           });
         };
+        /**
+         * @event THtmlItemsListController#item-added
+         * @type {object}
+         * @property {index} index
+         * @property {?HTMLElement} item
+         */
         this.#_triggerEvent('item-added', {
           index: index,
           item: item,
@@ -509,6 +784,14 @@ class THtmlItemsListController extends THtmlItemsListContainer {
     return index;
   }
 
+  /**
+   * @param {index}
+   * @param {any} [opt]
+   * @returns {bool}
+   * @fires THtmlItemsListController#list-clear
+   * @fires THtmlItemsListController#item-removed
+   * @description Deletes an element from an instance members.
+   */
   delItem(index, opt){
     const item = super.getItem(index);
     let isSUCCEED = item !== undefined;
@@ -530,9 +813,18 @@ class THtmlItemsListController extends THtmlItemsListContainer {
             // show default stub-item
             _status.isStubItemShown = this.#_stubs.showDefItem();
           };
+          /**
+           * @see THtmlItemsListController#list-clear
+           */
           this.#_triggerEvent('list-clear');
         } else {
           this.#_selects.delete(item);
+          /**
+           * @event THtmlItemsListController#item-removed
+           * @type {object}
+           * @property {index} index
+           * @property {?HTMLElement} item
+           */
           this.#_triggerEvent('item-removed', {
             index: Number(index),
             item: item,
@@ -552,11 +844,24 @@ class THtmlItemsListController extends THtmlItemsListContainer {
     return isSUCCEED;
   }
 
+  /**
+   * @param {index}
+   * @returns {bool}
+   * @private
+   * @fires THtmlItemsListController#item-selected
+   * @description Selects an element.
+   */
   #_selectItem(index){
     const item = super.getItem(index);
     const isSUCCEED = selectHtmlElement(item);
     if (isSUCCEED) {
       this.#_selects.add(item);
+      /**
+       * @event THtmlItemsListController#item-selected
+       * @type {object}
+       * @property {index} index
+       * @property {?HTMLElement} item
+       */
       this.#_triggerEvent('item-selected', {
         index: Number(index),
         item: item,
@@ -565,6 +870,16 @@ class THtmlItemsListController extends THtmlItemsListContainer {
     return isSUCCEED;
   }
 
+  /**
+   * @param {index}
+   * @param {object} [opt]
+   * @param {bool} [opt.ctrlKey=false]
+   * @param {bool} [opt.shiftKey=false]
+   * @param {bool} [opt.forceCI=false]
+   * @returns {none}
+   * @private
+   * @description Selects an element.
+   */
   #_selectItemEx(item, opt){
     const _selects = this.#_selects;
     let {
@@ -617,6 +932,12 @@ class THtmlItemsListController extends THtmlItemsListContainer {
     };
   }
 
+  /**
+   * @param {index}
+   * @param {bool} [opt=false]
+   * @returns {bool}
+   * @description Selects an element.
+   */
   selectItem(index, opt){
     const item = super.getItem(index);
     let isSUCCEED = isHTMLElement(item);
@@ -631,11 +952,23 @@ class THtmlItemsListController extends THtmlItemsListContainer {
     return isSUCCEED;
   }
 
+  /**
+   * @param {index}
+   * @returns {bool}
+   * @fires THtmlItemsListController#item-unselected
+   * @description Unselects an element.
+   */
   unselectItem(index){
     const item = super.getItem(index);
     let isSUCCEED = unselectHtmlElement(item);
     if (isSUCCEED) {
       this.#_selects.delete(item);
+      /**
+       * @event THtmlItemsListController#item-unselected
+       * @type {object}
+       * @property {index} index
+       * @property {?HTMLElement} item
+       */
       this.#_triggerEvent('item-unselected', {
         index: Number(index),
         item: item,
@@ -644,10 +977,22 @@ class THtmlItemsListController extends THtmlItemsListContainer {
     return isSUCCEED;
   }
 
+  /**
+   * @param {index}
+   * @returns {bool}
+   * @fires THtmlItemsListController#item-hidden
+   * @description Hides an element.
+   */
   hideItem(index){
     const item = super.getItem(index);
     let isSUCCEED = hideHtmlElement(item);
     if (isSUCCEED) {
+      /**
+       * @event THtmlItemsListController#item-hidden
+       * @type {object}
+       * @property {index} index
+       * @property {?HTMLElement} item
+       */
       this.#_triggerEvent('item-hidden', {
         index: Number(index),
         item: item,
@@ -656,10 +1001,22 @@ class THtmlItemsListController extends THtmlItemsListContainer {
     return isSUCCEED;
   }
 
+  /**
+   * @param {index}
+   * @returns {bool}
+   * @fires THtmlItemsListController#item-shown
+   * @description Shows an element.
+   */
   showItem(index){
     const item = super.getItem(index);
     let isSUCCEED = showHtmlElement(item);
     if (isSUCCEED) {
+      /**
+       * @event THtmlItemsListController#item-shown
+       * @type {object}
+       * @property {index} index
+       * @property {?HTMLElement} item
+       */
       this.#_triggerEvent('item-shown', {
         index: Number(index),
         item: item,
@@ -668,6 +1025,12 @@ class THtmlItemsListController extends THtmlItemsListContainer {
     return isSUCCEED;
   }
 
+  /**
+   * @param {ID_STRING}
+   * @param {func}
+   * @returns {none}
+   * @description Sets a callback function to handle event.
+   */
   on(name, evnt){
     pushEventHandler(this.#_events, name, evnt);
   }