@cntwg/html-ctrls-lists 0.0.30 → 0.0.32

package/lib/list.js

@@ -1,4 +1,4 @@
-// [v0.1.076-20260309]
+// [v0.1.088-20260505]
 
 // === module init block ===
 
@@ -21,7 +21,11 @@ const {
   CSS_CLASS_STRING,
 } = require('@cntwg/html-helper');
 
-const { THtmlStubItemsSet } = require('./lists-stubs.js');
+const {
+  THtmlStubItemsSet,
+  // * import types definitions *
+  IStubItemsSetOptions,
+} = require('./lists-stubs');
 
 // === module inner block ===
 
@@ -33,13 +37,29 @@ const {
   CSS_CLASS_DISABLED,
 } = CSS_CLASS_STRING;
 
+/**
+ * @typedef {Object} ISearchListElementResultOnFail
+ * @property {number} index - element index
+ * @property {null} item - found element
+ */
+
+/**
+ * @typedef {Object} ISearchListElementResultOnSuccess
+ * @property {number} index - element index
+ * @property {any} item - found element
+ */
+
+/**
+ * @typedef {ISearchListElementResultOnFail|ISearchListElementResultOnSuccess} ISearchListElementResult
+ */
+
 /**
  * Searches an element in a list by a given attributes of that element.
  * @function srchListElementByAttr
  * @param {TItemsListEx} list
  * @param {string} name - target attribute name
  * @param {string} [value=""] - target attribute value
- * @returns {object}
+ * @returns {ISearchListElementResult}
  * @inner
  */
 function srchListElementByAttr(list, name, value = '') {
@@ -91,8 +111,17 @@ class THtmlItemsListContainer {
   #_host;
   /** @type {TItemsListEx} */
   #_items;
-  /** @type {OPT_hlconsett} */
-  #_options;
+  /**
+   * A container settings
+   * @typedef {Object} THtmlItemsListContainerConfig
+   * @property {boolean} autoHideNewItems - indicates whether to hide a new element
+   * @property {boolean} markCurrentItem - indicates whether to mark a new element
+   *     as a current
+   * @property {string[]} itemBaseClassID - contains a base class attributes
+   *     applayed to each a newly added list member
+   */
+  /** @type {THtmlItemsListContainerConfig} */
+  #_config;
   /**
    * A container status
    * @typedef {Object} statILCont
@@ -105,7 +134,7 @@ class THtmlItemsListContainer {
 
   /**
    * Creates an instance of a list container
-   * @param {HTMLElement} host - host element
+   * @param {?HTMLElement} host - host element
    * @param {OPT_hlconsett} [opt] - options
    */
   constructor(host, opt) {
@@ -123,12 +152,17 @@ class THtmlItemsListContainer {
       itemBaseClassID,
     } = _options;
     if (typeof autoHideNewItems !== 'boolean') {
-      _options.autoHideNewItems = autoHideNewItems = false;
+      autoHideNewItems = false;
+      // // TODO: next line planned to be removed
+      _options.autoHideNewItems = autoHideNewItems;
     };
     if (typeof markCurrentItem !== 'boolean') {
-      _options.markCurrentItem = markCurrentItem = false;
+      markCurrentItem = false;
+      // // TODO: next line planned to be removed
+      _options.markCurrentItem = markCurrentItem;
     };
     itemBaseClassID = valueToClassList(itemBaseClassID, true);
+    // // TODO: next line planned to be removed
     _options.itemBaseClassID = itemBaseClassID;
     // init status
     /** @type {statILCont} */
@@ -138,7 +172,11 @@ class THtmlItemsListContainer {
     };
     this.#_status = _status;
     // save options
-    this.#_options = _options;
+    this.#_config = {
+      autoHideNewItems,
+      markCurrentItem,
+      itemBaseClassID,
+    };
   }
 
   [Symbol.iterator]() {
@@ -253,23 +291,51 @@ class THtmlItemsListContainer {
   /**
    * Checks if a given value is a valid index and
    * it fits an index range within an instance.
-   * @param {(number|string)} value - index value
+   * @param {number|string} value - index value
    * @returns {boolean}
+   * @deprecated
+   * @todo \[since v0.0.31] deprecated. Use
+   *     {@link THtmlItemsListContainer.checkIndex} instead
    */
   chkIndex(value) {
-    return this.#_items.chkIndex(value);
+    return this.#_items.checkIndex(value);
+  }
+
+  /**
+   * Checks if a given value is a valid index and
+   * it fits an index range within an instance.
+   * @since 0.0.31
+   * @param {number|string} value - index value
+   * @returns {boolean}
+   */
+  checkIndex(value) {
+    return this.#_items.checkIndex(value);
   }
 
   /**
    * Checks if a given value is a valid index and
    * it fits an index range within an instance.
-   * @param {(number|string)} value - value to check
+   * @param {number|string} value - value to check
    * @param {boolean} [opt=false] - defines a type of result
-   * @returns {(boolean|number)}
-   * @see TItemsListEx.chkIndexEx
+   * @returns {boolean|number}
+   * @deprecated
+   * @todo \[since v0.0.31] deprecated. Use
+   *     {@link THtmlItemsListContainer.checkIndex} or
+   *     {@link THtmlItemsListContainer.tryIndex} instead
    */
-  chkIndexEx(...args) {
-    return this.#_items.chkIndexEx(...args);
+  chkIndexEx(value, opt) {
+    return opt ? this.#_items.tryIndex(value) : this.#_items.checkIndex(value);
+  }
+
+  /**
+   * Returns an index in case a given value is a valid index value and not exceeds
+   * an index range within the list. If failed a `-1` returned
+   * @since 0.0.31
+   * @param {any} value - value to evaluate
+   * @returns {number}
+   */
+  tryIndex(value) {
+    return this.#_items.tryIndex(value);
   }
 
   /**
@@ -308,13 +374,13 @@ class THtmlItemsListContainer {
 
   /**
    * Sets a current index.
-   * @param {(number|string)} index - element index
+   * @param {number|string} index - element index
    * @returns {boolean}
    */
   setCurIndex(index) {
     const isSUCCEED = this.#_items.setIndex(index);
     if (isSUCCEED) {
-      const markCurrentItem = this.#_options.markCurrentItem;
+      const markCurrentItem = this.#_config.markCurrentItem;
       const _status = this.#_status;
       if (markCurrentItem && _status.curIndex !== -1) {
         unmarkCurrentHTMLElement(_status.curItem);
@@ -333,7 +399,7 @@ class THtmlItemsListContainer {
    */
   rstCurIndex() {
     const _status = this.#_status;
-    if (this.#_options.markCurrentItem && _status.curIndex !== -1) {
+    if (this.#_config.markCurrentItem && _status.curIndex !== -1) {
       unmarkCurrentHTMLElement(_status.curItem);
     };
     this.#_items.rstIndex();
@@ -343,7 +409,7 @@ class THtmlItemsListContainer {
 
   /**
    * Returns an item addressed by a given index.
-   * @param {(number|string)} index - element index
+   * @param {number|string} index - element index
    * @returns {?HTMLElement}
    */
   getItem(index) {
@@ -388,7 +454,7 @@ class THtmlItemsListContainer {
     );
     const isSUCCEED = index !== -1;
     if (isSUCCEED) {
-      const { autoHideNewItems, itemBaseClassID } = this.#_options;
+      const { autoHideNewItems, itemBaseClassID } = this.#_config;
       if (autoHideNewItems) hideHTMLElement(item);
       if (itemBaseClassID.length > 0) item.classList.add(...itemBaseClassID);
       if (forceCI) this.setCurIndex(index);
@@ -400,7 +466,7 @@ class THtmlItemsListContainer {
 
   /**
    * Deletes an item from an instance.
-   * @param {(number|string)} index - element index
+   * @param {number|string} index - element index
    * @param {any} [opt]
    * @param {boolean} [optEx=true]
    * @returns {boolean}
@@ -426,7 +492,7 @@ class THtmlItemsListContainer {
 
   /**
    * Selects an item addressed by a given index.
-   * @param {(number|string)} index - element index
+   * @param {number|string} index - element index
    * @param {boolean} [opt=false] - indicates whether to correct a current index
    * @returns {boolean}
    */
@@ -439,7 +505,7 @@ class THtmlItemsListContainer {
 
   /**
    * Unselects an item addressed by a given index.
-   * @param {(number|string)} index - element index
+   * @param {number|string} index - element index
    * @returns {boolean}
    */
   unselectItem(index) {
@@ -448,7 +514,7 @@ class THtmlItemsListContainer {
 
   /**
    * Hides an item addressed by a given index.
-   * @param {(number|string)} index - element index
+   * @param {number|string} index - element index
    * @returns {boolean}
    */
   hideItem(index) {
@@ -457,7 +523,7 @@ class THtmlItemsListContainer {
 
   /**
    * Shows an item addressed by a given index.
-   * @param {(number|string)} index - element index
+   * @param {number|string} index - element index
    * @returns {boolean}
    */
   showItem(index) {
@@ -466,7 +532,7 @@ class THtmlItemsListContainer {
 
   /**
    * Checks whether an item is selected.
-   * @param {(number|string)} index - element index
+   * @param {number|string} index - element index
    * @returns {boolean}
    */
   isSelectedItem(index) {
@@ -475,7 +541,7 @@ class THtmlItemsListContainer {
 
   /**
    * Checks whether an item is hidden.
-   * @param {(number|string)} index - element index
+   * @param {number|string} index - element index
    * @returns {boolean}
    */
   isHiddenItem(index) {
@@ -483,15 +549,7 @@ class THtmlItemsListContainer {
   }
 
 };
-exports.THtmlItemsListContainer = THtmlItemsListContainer;
-
-/**
- * A an options set for a `THtmlStubItemsSet`-class constructor
- * @typedef {Object} OPT_stubconsett
- * @property {(any[])} items - array of `name`-`element` pairs
- * @property {string} [defaultItem] - a default element name
- * @property {boolean} [force=false] - run in a force mode
- */
+module.exports.THtmlItemsListContainer = THtmlItemsListContainer;
 
 /**
  * An options set for `THtmlItemsListController`-class
@@ -500,7 +558,7 @@ exports.THtmlItemsListContainer = THtmlItemsListContainer;
  *     a new element
  * @property {boolean} [markCurrentItem=false] - indicates whether to mark
  *     a current element
- * @property {(string|string[])} [itemBaseClassID] - contains a base class
+ * @property {string|string[]} [itemBaseClassID] - contains a base class
  *     attributes applayed to each a newly added list member
  * @property {boolean} [showStubsIfEmpty=false] - indicates whether to show
  *     stubs if empty
@@ -508,7 +566,7 @@ exports.THtmlItemsListContainer = THtmlItemsListContainer;
  *    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] - stub elements options
+ * @property {IStubItemsSetOptions} [stubs] - stub elements options
  */
 
 /**
@@ -607,9 +665,8 @@ class THtmlItemsListController extends THtmlItemsListContainer {
   }
 
   /**
-   * @param {Event} e - event
+   * @param {UIEvent} e - event
    * @returns {void}
-   * @private
    */
   #_on_will_select_item = (e) => {
     //console.log('THtmlItemsListController._on_will_select_item() ==> was called...');
@@ -674,7 +731,6 @@ class THtmlItemsListController extends THtmlItemsListContainer {
    * @param {string} name - event name
    * @param {...any} args
    * @returns {void}
-   * @private
    * @see triggerEventHandler
    */
   #_triggerEvent = (name, ...args) => {
@@ -754,10 +810,9 @@ class THtmlItemsListController extends THtmlItemsListContainer {
 
   /**
    * Sets a current index.
-   * @param {(number|string)} index - element index
+   * @param {number|string} index - element index
    * @returns {boolean}
    * @fires THtmlItemsListController#current-item-chosen
-   * @private
    */
   #_setCurIndex(index) {
     const isSUCCEED = super.setCurIndex(index);
@@ -776,7 +831,7 @@ class THtmlItemsListController extends THtmlItemsListContainer {
 
   /**
    * Sets a current index.
-   * @param {(number|string)} index - element index
+   * @param {number|string} index - element index
    * @returns {boolean}
    */
   setCurIndex(index) {
@@ -868,7 +923,7 @@ class THtmlItemsListController extends THtmlItemsListContainer {
 
   /**
    * Deletes an element from an instance members.
-   * @param {(number|string)} index - element index
+   * @param {number|string} index - element index
    * @param {any} [opt]
    * @returns {boolean}
    * @fires THtmlItemsListController#list-clear
@@ -928,15 +983,14 @@ class THtmlItemsListController extends THtmlItemsListContainer {
 
   /**
    * Selects an element.
-   * @param {(number|string)} index - element index
+   * @param {number|string} index - element index
    * @returns {boolean}
-   * @private
    * @fires THtmlItemsListController#item-selected
    */
   #_selectItem(index) {
     const item = super.getItem(index);
-    const isSUCCEED = selectHTMLElement(item);
-    if (isSUCCEED) {
+    let isSucceed = false;
+    if (item && (isSucceed = selectHTMLElement(item))) {
       this.#_selects.add(item);
       /**
        * @event THtmlItemsListController#item-selected
@@ -949,18 +1003,22 @@ class THtmlItemsListController extends THtmlItemsListContainer {
         item: item,
       });
     };
-    return isSUCCEED;
+    return isSucceed;
   }
 
+  /**
+   * 
+   * @typedef {Object} OPT_selectStat
+   * @property {boolean} [ctrlKey=false]
+   * @property {boolean} [shiftKey=false]
+   * @property {boolean} [forceCI=false]
+   */
+
   /**
    * Selects an element.
-   * @param {?HTMLElement} item - element
-   * @param {object} [opt]
-   * @param {boolean} [opt.ctrlKey=false]
-   * @param {boolean} [opt.shiftKey=false]
-   * @param {boolean} [opt.forceCI=false]
+   * @param {HTMLElement} item - element
+   * @param {OPT_selectStat} opt - select options
    * @returns {void}
-   * @private
    */
   #_selectItemEx(item, opt){
     const _selects = this.#_selects;
@@ -1016,34 +1074,35 @@ class THtmlItemsListController extends THtmlItemsListContainer {
 
   /**
    * Selects an element.
-   * @param {(number|string)} index - element index
+   * @param {number|string} index - element index
    * @param {boolean} [opt=false] - indicates whether to correct a current index
    * @returns {boolean}
    */
   selectItem(index, opt) {
     const item = super.getItem(index);
-    let isSUCCEED = isHTMLElement(item);
-    if (isSUCCEED) {
+    let isSucceed = false;
+    if (isHTMLElement(item)) {
       const forceCI = typeof opt === 'boolean' ? opt : false;
       this.#_selectItemEx(item, {
         ctrlKey: false,
         shiftKey: false,
         forceCI: forceCI,
       });
+      isSucceed = true;
     };
-    return isSUCCEED;
+    return isSucceed;
   }
 
   /**
    * Unselects an element.
-   * @param {(number|string)} index - element index
+   * @param {number|string} index - element index
    * @returns {boolean}
    * @fires THtmlItemsListController#item-unselected
    */
   unselectItem(index) {
     const item = super.getItem(index);
-    let isSUCCEED = unselectHTMLElement(item);
-    if (isSUCCEED) {
+    let isSucceed = false;
+    if (item && (isSucceed = unselectHTMLElement(item))) {
       this.#_selects.delete(item);
       /**
        * @event THtmlItemsListController#item-unselected
@@ -1056,19 +1115,19 @@ class THtmlItemsListController extends THtmlItemsListContainer {
         item: item,
       });
     };
-    return isSUCCEED;
+    return isSucceed;
   }
 
   /**
    * Hides an element.
-   * @param {(number|string)} index - element index
+   * @param {number|string} index - element index
    * @returns {boolean}
    * @fires THtmlItemsListController#item-hidden
    */
   hideItem(index) {
     const item = super.getItem(index);
-    let isSUCCEED = hideHTMLElement(item);
-    if (isSUCCEED) {
+    let isSucceed = false;
+    if (item && (isSucceed = hideHTMLElement(item))) {
       /**
        * @event THtmlItemsListController#item-hidden
        * @type {Object}
@@ -1080,19 +1139,19 @@ class THtmlItemsListController extends THtmlItemsListContainer {
         item: item,
       });
     };
-    return isSUCCEED;
+    return isSucceed;
   }
 
   /**
    * Shows an element.
-   * @param {(number|string)} index - element index
+   * @param {number|string} index - element index
    * @returns {boolean}
    * @fires THtmlItemsListController#item-shown
    */
   showItem(index) {
     const item = super.getItem(index);
-    let isSUCCEED = showHTMLElement(item);
-    if (isSUCCEED) {
+    let isSucceed = false;
+    if (item && (isSucceed = showHTMLElement(item))) {
       /**
        * @event THtmlItemsListController#item-shown
        * @type {Object}
@@ -1104,7 +1163,7 @@ class THtmlItemsListController extends THtmlItemsListContainer {
         item: item,
       });
     };
-    return isSUCCEED;
+    return isSucceed;
   }
 
   /**
@@ -1118,8 +1177,4 @@ class THtmlItemsListController extends THtmlItemsListContainer {
   }
 
 };
-exports.THtmlItemsListController = THtmlItemsListController;
-
-// === module exports block ===
-
-exports.THtmlStubItemsSet = THtmlStubItemsSet;
+module.exports.THtmlItemsListController = THtmlItemsListController;

package/lib/lists-btn.d.ts

@@ -0,0 +1,63 @@
+/**
+ * A description for list buttons set.
+ */
+export type listButtonsSetDesc = {
+    /**
+     * - button 'move to first'
+     */
+    btnFirst: HTMLElement | null;
+    /**
+     * - button 'move to previous'
+     */
+    btnPrev: HTMLElement | null;
+    /**
+     * - button 'move to next'
+     */
+    btnNext: HTMLElement | null;
+    /**
+     * - button 'move to last'
+     */
+    btnLast: HTMLElement | null;
+};
+export const BTS_DEF_GROUP_NAME: "all";
+
+/**
+ * This class implements an interface of a pre-defined
+ * buttons set that is used in pair with a list elements.
+ * A set provide a buttons: <next>, <previous>, <first> and <last>.
+ */
+export class THtmlListButtonsController {
+    /**
+     * Creates an instance of a buttons set.
+     */
+    constructor(opt?: listButtonsSetDesc);
+    /**
+     * Disables all buttons.
+     */
+    disableAll(): void;
+    /**
+     * Disables all buttons in 'move_bkwd' group.
+     */
+    disableBkwd(): void;
+    /**
+     * Disables all buttons in 'move_frwd' group.
+     */
+    disableFrwd(): void;
+    /**
+     * Enables all buttons.
+     */
+    enableAll(): void;
+    /**
+     * Enables all buttons in 'move_bkwd' group.
+     */
+    enableBkwd(): void;
+    /**
+     * Enables all buttons in 'move_frwd' group.
+     */
+    enableFrwd(): void;
+    /**
+     * Sets a callback function to handle event.
+     */
+    on(name: string, evnt: Function): void;
+    #private;
+}

package/lib/lists-btn.js

@@ -1,4 +1,4 @@
-// [v0.1.061-20260309]
+// [v0.1.063-20260505]
 
 // === module init block ===
 
@@ -18,7 +18,7 @@ const {
 
 const {
   readOnClickEventInfo,
-} = require('./mod-hfunc.js');
+} = require('./mod-hfunc');
 
 // === module inner block ===
 
@@ -33,6 +33,7 @@ const {
 // === module main block ===
 
 const BTS_DEF_GROUP_NAME = 'all';
+module.exports.BTS_DEF_GROUP_NAME = BTS_DEF_GROUP_NAME;
 
 /**
  * A description for list buttons set.
@@ -103,10 +104,9 @@ class THtmlListButtonsController {
   }
 
   /**
-   * @param {Event} e - event
+   * @param {UIEvent} e - event
    * @param {string} key - button ID
    * @returns {void}
-   * @private
    */
   #_on_btn_pressed = (e, key) => {
     //console.log(`THtmlListButtonsController._on_btn_pressed().key(${key}) ==> was called...`);
@@ -125,7 +125,6 @@ class THtmlListButtonsController {
    * @param {string} name - event name
    * @param {...any} args
    * @returns {void}
-   * @private
    * @see triggerEventHandler
    */
   #_triggerEvent = (name, ...args) => {
@@ -194,8 +193,4 @@ class THtmlListButtonsController {
     pushEventHandler(this.#_events, name, evnt);
   }
 };
-exports.THtmlListButtonsController = THtmlListButtonsController;
-
-// === module exports block ===
-
-exports.BTS_DEF_GROUP_NAME = BTS_DEF_GROUP_NAME;
+module.exports.THtmlListButtonsController = THtmlListButtonsController;