@cntwg/html-helper 0.0.26 → 0.0.27

package/lib/html-ctrls/list.js

@@ -1,4 +1,4 @@
-// [v0.1.070-20250504]
+// [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);
@@ -652,7 +653,7 @@ class THtmlItemsListController extends THtmlItemsListContainer {
   };
 
   /**
-   * @param {string} name
+   * @param {string} name - event name
    * @param {...any} args
    * @returns {void}
    * @private
@@ -696,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
@@ -716,8 +717,8 @@ class THtmlItemsListController extends THtmlItemsListContainer {
   }
 
   /**
+   * Locks an element selection.
    * @returns {void}
-   * @description Locks an element selection.
    */
   lockItemsSelection() {
     if (this.#_options.allowSelectionLocks) {
@@ -726,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);
@@ -756,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 {
@@ -785,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);
@@ -848,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);
@@ -908,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);
@@ -934,6 +935,7 @@ class THtmlItemsListController extends THtmlItemsListContainer {
   }
 
   /**
+   * Selects an element.
    * @param {?HTMLElement} item - element
    * @param {object} [opt]
    * @param {boolean} [opt.ctrlKey=false]
@@ -941,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;
@@ -996,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);
@@ -1016,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);
@@ -1041,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);
@@ -1065,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);
@@ -1089,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);

package/lib/html-ctrls/lists-btn.js

@@ -1,4 +1,4 @@
-// [v0.1.054-20250509]
+// [v0.1.056-20250827]
 
 // === module init block ===
 
@@ -7,11 +7,11 @@ const {
 } = require('@ygracs/bsfoc-lib-js');
 
 const {
+  isHTMLButton,
   CSS_CLASS_STRING,
 } = require('../html-helper-lib.js');
 
 const {
-  isHTMLButton,
   THtmlButtonsSet,
 }  = require('./buttons.js');
 
@@ -42,6 +42,15 @@ const BTS_DEF_GROUP_NAME = 'all';
  * (* class definitions *)
  */
 
+/**
+ * A description for list buttons set.
+ * @typedef {Object} listButtonsSetDesc
+ * @property {?HTMLElement} btnFirst - button 'move to first'
+ * @property {?HTMLElement} btnPrev - button 'move to previous'
+ * @property {?HTMLElement} btnNext - button 'move to next'
+ * @property {?HTMLElement} btnLast - button 'move to last'
+ */
+
 /**
  * @classdesc This class implements an interface of a pre-defined
  *            buttons set that is used in pair with a list elements.
@@ -54,17 +63,8 @@ class THtmlListButtonsController {
   #_events;
 
   /**
-   * @typedef {Object} listButtonsSetDesc
-   * @property {?HTMLElement} btnFirst - button 'move to first'
-   * @property {?HTMLElement} btnPrev - button 'move to previous'
-   * @property {?HTMLElement} btnNext - button 'move to next'
-   * @property {?HTMLElement} btnLast - button 'move to last'
-   * @description A description for list buttons set.
-   */
-
-  /**
+   * Creates an instance of a buttons set.
    * @param {listButtonsSetDesc} [opt] - an options
-   * @description Creates an instance of a buttons set.
    */
   constructor(opt) {
     // load controls
@@ -141,8 +141,8 @@ class THtmlListButtonsController {
   }
 
   /**
+   * Disables all buttons.
    * @returns {void}
-   * @description Disables all buttons.
    */
   disableAll() {
     const _btnSet = this.#_btnSet;
@@ -151,24 +151,24 @@ class THtmlListButtonsController {
   }
 
   /**
+   * Disables all buttons in 'move_bkwd' group.
    * @returns {void}
-   * @description Disables all buttons in 'move_bkwd' group.
    */
   disableBkwd() {
     this.#_btnSet.disableGroup('move_bkwd');
   }
 
   /**
+   * Disables all buttons in 'move_frwd' group.
    * @returns {void}
-   * @description Disables all buttons in 'move_frwd' group.
    */
   disableFrwd() {
     this.#_btnSet.disableGroup('move_frwd');
   }
 
   /**
+   * Enables all buttons.
    * @returns {void}
-   * @description Enables all buttons.
    */
   enableAll() {
     const _btnSet = this.#_btnSet;
@@ -177,26 +177,26 @@ class THtmlListButtonsController {
   }
 
   /**
+   * Enables all buttons in 'move_bkwd' group.
    * @returns {void}
-   * @description Enables all buttons in 'move_bkwd' group.
    */
   enableBkwd() {
     this.#_btnSet.enableGroup('move_bkwd');
   }
 
   /**
+   * Enables all buttons in 'move_frwd' group.
    * @returns {void}
-   * @description Enables all buttons in 'move_frwd' group.
    */
   enableFrwd() {
     this.#_btnSet.enableGroup('move_frwd');
   }
 
   /**
+   * Sets a callback function to handle event.
    * @param {string} name - event name
    * @param {func} evnt - callback function
    * @returns {void}
-   * @description Sets a callback function to handle event.
    */
   on(name, evnt) {
     pushEventHandler(this.#_events, name, evnt);