@cntwg/html-ctrls-lists 0.0.31 → 0.0.32

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+#### *v0.0.32*
+
+Pre-release version.
+
+> - update `html-ctrls-list.md`;
+> - update dependency on `@ygracs/lists-lib-js` module to v0.2.1;
+> - update dependency on `@cntwg/html-ctrls-buttons` module to v0.1.1;
+> - (THtmlStubItemsSet) change method behavior: `loadItems`;
+> - some fixes.
+
 #### *v0.0.31*
 
 Pre-release version.

package/doc/html-ctrls-list.md

@@ -1,6 +1,6 @@
->|***rev.*:**|0.1.25|
+>|***rev.*:**|0.1.27|
 >|:---|---:|
->|date:|2026-04-18|
+>|date:|2026-05-05|
 
 ## Introduction
 
@@ -119,12 +119,12 @@ This method returns `true` if the container has at least one item.
 <a name="THtmlItemsListContainer+chkIndex"></a>
 ###### **chkIndex(value)** => `boolean`
 
-> WARNING: \[since `v0.0.3x`] this method deprecated (*use [`checkIndex`](#THtmlItemsListContainer+checkIndex) method instead*).
+> WARNING: \[since `v0.0.31`] this method deprecated (*use [`checkIndex`](#THtmlItemsListContainer+checkIndex) method instead*).
 
 <a name="THtmlItemsListContainer+checkIndex"></a>
 ###### **checkIndex(value)** => `boolean`
 
-> since: \[`v0.0.3x`]
+> since: \[`v0.0.31`]
 
 This method checks if the given `value` represents a valid index value and fits the range of all possible indexes belonging to the list instance. If so `true` is returned.
 
@@ -135,7 +135,7 @@ This method checks if the given `value` represents a valid index value and fits
 <a name="THtmlItemsListContainer+tryIndex"></a>
 ###### **tryIndex(value)** => `number`
 
-> since: \[`v0.0.3x`]
+> since: \[`v0.0.31`]
 
 This method evaluates whether the given `value` represents a valid index value and fits the range of all possible indexes belonging to the list instance. If so an index value returned. If failed a `-1` will be returned.
 
@@ -159,7 +159,7 @@ The `mode` parameter treats as follows:
 - if set to `true`, the result returned by the method is an index;
 - if not given or has a type of not a `boolean`, the default value is used.
 
-> WARNING: \[since `v0.0.3x`] this method deprecated (*use [`checkIndex`](#THtmlItemsListContainer+checkIndex) or [`tryIndex`](#THtmlItemsListContainer+tryIndex) method instead*).
+> WARNING: \[since `v0.0.31`] this method deprecated (*use [`checkIndex`](#THtmlItemsListContainer+checkIndex) or [`tryIndex`](#THtmlItemsListContainer+tryIndex) method instead*).
 
 <a name="THtmlItemsListContainer+srchIndex"></a>
 ###### **srchIndex(item)** => `number`
@@ -452,12 +452,12 @@ This method returns `true` if the list has at least one item.
 <a name="THtmlItemsListController+chkIndex"></a>
 ###### **chkIndex(value)** => `boolean`
 
-> WARNING: \[since `v0.0.3x`] this method deprecated (*use [`checkIndex`](#THtmlItemsListController+checkIndex) method instead*).
+> WARNING: \[since `v0.0.31`] this method deprecated (*use [`checkIndex`](#THtmlItemsListController+checkIndex) method instead*).
 
 <a name="THtmlItemsListController+checkIndex"></a>
 ###### **checkIndex(value)** => `boolean`
 
-> since: \[`v0.0.3x`]
+> since: \[`v0.0.31`]
 
 This method checks if the given `value` represents a valid index value and fits the range of all possible indexes belonging to the list instance. If so `true` is returned.
 
@@ -468,7 +468,7 @@ This method checks if the given `value` represents a valid index value and fits
 <a name="THtmlItemsListController+tryIndex"></a>
 ###### **tryIndex(value)** => `number`
 
-> since: \[`v0.0.3x`]
+> since: \[`v0.0.31`]
 
 This method evaluates whether the given `value` represents a valid index value and fits the range of all possible indexes belonging to the list instance. If so an index value returned. If failed a `-1` will be returned.
 
@@ -490,7 +490,7 @@ If `mode` parameter set to `false` (*its default value*), the result returned by
 
 If `mode` parameter set to `true`, the result returned by the method has an index type.
 
-> WARNING: \[since `v0.0.3x`] this method deprecated (*use [`checkIndex`](#THtmlItemsListController+checkIndex) or [`tryIndex`](#THtmlItemsListController+tryIndex) method instead*).
+> WARNING: \[since `v0.0.31`] this method deprecated (*use [`checkIndex`](#THtmlItemsListController+checkIndex) or [`tryIndex`](#THtmlItemsListController+tryIndex) method instead*).
 
 <a name="THtmlItemsListController+srchIndex"></a>
 ###### **srchIndex(item)** => `number`
@@ -816,6 +816,7 @@ This class methods loads an items given by `list` in the set and returned quanti
 | `options` | `boolean`, `object` | --- | an options |
 
 > \[!] NOTE: *`[since v0.0.25]`* the use of a booleans as an `options` value is deprecated and will be dropped soon.
+> \[!] NOTE: *`[since v0.0.32]`* the use of an array as an `data` value is deprecated and will be dropped soon.
 
 If the `data` parameter is an `object` that contains the following set of values:
 

package/index.d.ts

@@ -0,0 +1,19 @@
+import {
+  THtmlStubItemsSet,
+} from "./lib/lists-stubs";
+
+import {
+  BTS_DEF_GROUP_NAME,
+  THtmlListButtonsController,
+} from "./lib/lists-btn";
+
+import {
+  THtmlItemsListContainer, THtmlItemsListController,
+} from "./lib/list";
+
+export {
+  THtmlStubItemsSet,
+  THtmlItemsListContainer, THtmlItemsListController,
+  BTS_DEF_GROUP_NAME,
+  THtmlListButtonsController,
+};

package/lib/list.d.ts

@@ -0,0 +1,278 @@
+export type ISearchListElementResultOnFail = {
+    /**
+     * - element index
+     */
+    index: number;
+    /**
+     * - found element
+     */
+    item: null;
+};
+export type ISearchListElementResultOnSuccess = {
+    /**
+     * - element index
+     */
+    index: number;
+    /**
+     * - found element
+     */
+    item: any;
+};
+export type ISearchListElementResult = ISearchListElementResultOnFail | ISearchListElementResultOnSuccess;
+/**
+ * An options set for `THtmlItemsListContainer`-class
+ */
+export type OPT_hlconsett = {
+    /**
+     * - indicates whether to hide a new element
+     */
+    autoHideNewItems?: boolean;
+    /**
+     * - indicates whether to mark a current element
+     */
+    markCurrentItem?: boolean | undefined;
+    /**
+     * - contains a base class
+     * attributes applayed to each a newly added list member
+     */
+    itemBaseClassID?: string | string[];
+};
+/**
+ * An options set for `THtmlItemsListController`-class
+ */
+export type OPT_hlctlsett = {
+    /**
+     * - indicates whether to hide a new element
+     */
+    autoHideNewItems?: boolean;
+    /**
+     * - indicates whether to mark a current element
+     */
+    markCurrentItem?: boolean;
+    /**
+     * - contains a base class
+     * attributes applayed to each a newly added list member
+     */
+    itemBaseClassID?: string | string[];
+    /**
+     * - indicates whether to show stubs if empty
+     */
+    showStubsIfEmpty?: boolean;
+    /**
+     * - indicates whether a selection of the elements group is allowed
+     */
+    allowGroupSelection?: boolean;
+    /**
+     * - indicates whether locking of an element selection is allowed
+     */
+    allowSelectionLocks?: boolean;
+    /**
+     * - stub elements options
+     */
+    stubs?: IStubItemsSetOptions | undefined;
+};
+import type { IStubItemsSetOptions } from "./lists-stubs";
+
+/**
+ * This class implements an interfaco for a list container
+ */
+export class THtmlItemsListContainer {
+    /**
+     * Creates an instance of a list container
+     */
+    constructor(host: HTMLElement | null, opt?: OPT_hlconsett);
+    /**
+     * Contains a Qty of an elements
+     */
+    get count(): number;
+    /**
+     * Contains an index of the current element
+     */
+    get curIndex(): number;
+    /**
+     * Returns a minimum value of an index
+     */
+    get minIndex(): number;
+    /**
+     * Returns a maximum value of an index
+     */
+    get maxIndex(): number;
+    /**
+     * Returns a value of a previous index
+     */
+    get prevIndex(): number;
+    /**
+     * Returns a value of a next index
+     */
+    get nextIndex(): number;
+    /**
+     * Returns an element in the current index
+     */
+    get curItem(): HTMLElement | null;
+    /**
+     * Clears an instance content.
+     */
+    clear(): void;
+    /**
+     * Checks if an instance contains no items.
+     */
+    isEmpty(): boolean;
+    /**
+     * Checks if an instance contains any items.
+     */
+    isNotEmpty(): boolean;
+    /**
+     * Checks if a given value is a valid index and
+     * it fits an index range within an instance.
+     * @deprecated
+     * @todo \[since v0.0.31] deprecated. Use
+     *     {@link THtmlItemsListContainer.checkIndex} instead
+     */
+    chkIndex(value: number | string): boolean;
+    /**
+     * Checks if a given value is a valid index and
+     * it fits an index range within an instance.
+     * @since 0.0.31
+     */
+    checkIndex(value: number | string): boolean;
+    /**
+     * Checks if a given value is a valid index and
+     * it fits an index range within an instance.
+     * @deprecated
+     * @todo \[since v0.0.31] deprecated. Use
+     *     {@link THtmlItemsListContainer.checkIndex} or
+     *     {@link THtmlItemsListContainer.tryIndex} instead
+     */
+    chkIndexEx(value: number | string, opt?: boolean): boolean | number;
+    /**
+     * 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
+     */
+    tryIndex(value: any): number;
+    /**
+     * Returns an index of a given element.
+     * @param {HTMLElement} item  - element to search
+     * @todo add 2nd param
+     * @see TItemsListEx.srchIndex
+     */
+    srchIndex(item: HTMLElement): number;
+    /**
+     * Returns an index of an element wich has an attribute
+     * with a given name and value.
+     */
+    srchIndexByAttr(name: string, value?: any): number;
+    /**
+     * Returns an index of an element wich has a given ID.
+     */
+    srchIndexByID(value: string): number;
+    /**
+     * Sets a current index.
+     */
+    setCurIndex(index: number | string): boolean;
+    /**
+     * Resets a current index.
+     */
+    rstCurIndex(): void;
+    /**
+     * Returns an item addressed by a given index.
+     */
+    getItem(index: number | string): HTMLElement | null;
+    /**
+     * Returns an item wich has an attribute with a given name and value.
+     */
+    getItemByAttr(name: string, value?: any): HTMLElement | null;
+    /**
+     * Returns an item wich has a given ID.
+     */
+    getItemByID(value: string): HTMLElement | null;
+    /**
+     * Adds an item to an instance.
+     */
+    addItem(item: HTMLElement, opt?: boolean): number;
+    /**
+     * Deletes an item from an instance.
+     */
+    delItem(index: number | string, opt?: any, optEx?: boolean): boolean;
+    /**
+     * Selects an item addressed by a given index.
+     */
+    selectItem(index: number | string, opt?: boolean): boolean;
+    /**
+     * Unselects an item addressed by a given index.
+     */
+    unselectItem(index: number | string): boolean;
+    /**
+     * Hides an item addressed by a given index.
+     */
+    hideItem(index: number | string): boolean;
+    /**
+     * Shows an item addressed by a given index.
+     */
+    showItem(index: number | string): boolean;
+    /**
+     * Checks whether an item is selected.
+     */
+    isSelectedItem(index: number | string): boolean;
+    /**
+     * Checks whether an item is hidden.
+     */
+    isHiddenItem(index: number | string): boolean;
+    [Symbol.iterator](): {
+        next: () => {
+            done: boolean;
+            value: HTMLElement | null;
+        } | {
+            done: boolean;
+            value: undefined;
+        };
+        return(): {
+            done: boolean;
+            value: undefined;
+        };
+    };
+    #private;
+}
+
+/**
+ * This class enhanced a capabilities implemented
+ * in the `THtmlItemsListContainer` class
+ */
+export class THtmlItemsListController extends THtmlItemsListContainer {
+    /**
+     * Creates a new instance of the class.
+     */
+    constructor(host: HTMLElement | null, opt?: OPT_hlctlsett);
+    /**
+     * Returns a list of the selected elements
+     */
+    get SelectedItems(): HTMLElement[];
+    /**
+     * Returns a `THtmlStubItemsSet` instance
+     */
+    get StubItems(): THtmlStubItemsSet;
+    /**
+     * Indicates whether a selection is locked
+     */
+    get isSelectionLocked(): boolean;
+    /**
+     * Locks an element selection.
+     */
+    lockItemsSelection(): void;
+    /**
+     * Unlocks an element selection.
+     */
+    unlockItemsSelection(): void;
+    /**
+     * Deletes an element from an instance members.
+     * @fires THtmlItemsListController#list-clear
+     * @fires THtmlItemsListController#item-removed
+     */
+    delItem(index: number | string, opt?: any): boolean;
+    /**
+     * Sets a callback function to handle event.
+     */
+    on(name: string, evnt: Function): void;
+    #private;
+}
+import { THtmlStubItemsSet } from "./lists-stubs";

package/lib/list.js

@@ -1,4 +1,4 @@
-// [v0.1.079-20260416]
+// [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]() {
@@ -256,7 +294,7 @@ class THtmlItemsListContainer {
    * @param {number|string} value - index value
    * @returns {boolean}
    * @deprecated
-   * @todo \[since v0.0.3x] deprecated. Use
+   * @todo \[since v0.0.31] deprecated. Use
    *     {@link THtmlItemsListContainer.checkIndex} instead
    */
   chkIndex(value) {
@@ -266,7 +304,7 @@ class THtmlItemsListContainer {
   /**
    * Checks if a given value is a valid index and
    * it fits an index range within an instance.
-   * @since 0.0.3x
+   * @since 0.0.31
    * @param {number|string} value - index value
    * @returns {boolean}
    */
@@ -280,8 +318,8 @@ class THtmlItemsListContainer {
    * @param {number|string} value - value to check
    * @param {boolean} [opt=false] - defines a type of result
    * @returns {boolean|number}
-   * @see TItemsListEx.chkIndexEx
-   * @todo \[since v0.0.3x] deprecated. Use
+   * @deprecated
+   * @todo \[since v0.0.31] deprecated. Use
    *     {@link THtmlItemsListContainer.checkIndex} or
    *     {@link THtmlItemsListContainer.tryIndex} instead
    */
@@ -292,7 +330,7 @@ class THtmlItemsListContainer {
   /**
    * 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.3x
+   * @since 0.0.31
    * @param {any} value - value to evaluate
    * @returns {number}
    */
@@ -336,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);
@@ -361,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();
@@ -371,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) {
@@ -416,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);
@@ -428,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}
@@ -454,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}
    */
@@ -467,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) {
@@ -476,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) {
@@ -485,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) {
@@ -494,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) {
@@ -503,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) {
@@ -511,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
@@ -528,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
@@ -536,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
  */
 
 /**
@@ -635,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...');
@@ -702,7 +731,6 @@ class THtmlItemsListController extends THtmlItemsListContainer {
    * @param {string} name - event name
    * @param {...any} args
    * @returns {void}
-   * @private
    * @see triggerEventHandler
    */
   #_triggerEvent = (name, ...args) => {
@@ -782,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);
@@ -804,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) {
@@ -896,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
@@ -956,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
@@ -977,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;
@@ -1044,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
@@ -1084,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}
@@ -1108,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}
@@ -1132,7 +1163,7 @@ class THtmlItemsListController extends THtmlItemsListContainer {
         item: item,
       });
     };
-    return isSUCCEED;
+    return isSucceed;
   }
 
   /**
@@ -1146,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;

package/lib/lists-stubs.d.ts

@@ -0,0 +1,134 @@
+/**
+ * A set of options for a `THtmlStubItemsSet`-class constructor
+ */
+export type IStubItemsSetOptions = {
+    /**
+     * - array of `name`-`element` pairs
+     */
+    items: pairOfNameAndElement[];
+    /**
+     * - a default element name
+     */
+    defaultItem?: string;
+    /**
+     * - run in a force mode
+     */
+    force?: boolean | undefined;
+};
+export const IStubItemsSetOptions: IStubItemsSetOptions;
+/**
+ * A `name`-`element` pair
+ */
+export type pairOfNameAndElement = [ name: string, item: HTMLElement ];
+/**
+ * A settings to load a stub-elements.
+ */
+export type OPT_ldstubs = {
+    /**
+     * - a default element name
+     * @deprecated
+     */
+    defaultItem?: string;
+    /**
+     * - to clear before load an elements
+     */
+    useClear?: boolean;
+    /**
+     * - run in a force mode
+     */
+    force?: boolean;
+};
+/**
+ * A stub-elements list descriptor
+ */
+export type IStubEListDesc = {
+    /**
+     * - array of `name`-`element` pairs
+     */
+    items: pairOfNameAndElement[];
+    /**
+     * - a default element name
+     */
+    defaultItem?: string;
+};
+
+/**
+ * This class implements an interface of a stub-items set
+ */
+export class THtmlStubItemsSet {
+    /**
+     * Creates an instance of a stub-items set
+     * @todo [since v0.0.26] use of an `array`-type as a value of an `opt` is deprecated
+     */
+    constructor(host: HTMLElement, opt?: pairOfNameAndElement[] | IStubEListDesc | IStubItemsSetOptions);
+    /**
+     * Defines a default element name
+     * @type {string}
+     */
+    set defItem(name: string);
+    get defItem(): string;
+    /**
+     * Contains a Qty of an elements
+     * @type {number}
+     */
+    get count(): number;
+    /**
+     * Clears an instance content.
+     * @todo check if any item is shown
+     */
+    clear(): void;
+    /**
+     * Sets a default item.
+     */
+    setDefItem(name: string): boolean;
+    /**
+     * Resets a default item.
+     * @todo check if item is shown
+     */
+    rstDefItem(): void;
+    /**
+     * Checks if an item exists.
+     */
+    hasItem(name: string): boolean;
+    /**
+     * Checks if any items exists.
+     */
+    hasItems(): boolean;
+    /**
+     * Returns an item by its name.
+     */
+    getItem(name: string): HTMLElement | null;
+    /**
+     * Adds an item to an instance members.
+     */
+    addItem(name: string, item: HTMLElement, opt?: boolean): boolean;
+    /**
+     * Deletes an item from an instance members.
+     * @todo check if item is shown
+     */
+    delItem(name: string): boolean;
+    /**
+     * Shows an item.
+     */
+    showItem(name: string): boolean;
+    /**
+     * Shows a default item.
+     */
+    showDefItem(): boolean;
+    /**
+     * Hides an item.
+     */
+    hideItem(name: string): boolean;
+    /**
+     * Hides a default item.
+     */
+    hideDefItem(): boolean;
+    /**
+     * Adds an items to an instance members.
+     * @todo [since 0.0.25] deprecate use of `opt` as `boolean`
+     * @todo [since v0.0.26] for `OPT_ldstubs` a `defaultItem`-option deprecated
+     * @todo [since 0.0.32] deprecate use of `data` as `array`
+     */
+    loadItems(data: pairOfNameAndElement[] | IStubEListDesc, opt?: boolean | OPT_ldstubs): number;
+    #private;
+}

package/lib/lists-stubs.js

@@ -1,4 +1,4 @@
-// [v0.1.053-20260309]
+// [v0.1.057-20260505]
 
 // === module init block ===
 
@@ -14,6 +14,11 @@ const {
 
 // === module main block ===
 
+/**
+ * A `name`-`element` pair
+ * @typedef {any[]} pairOfNameAndElement
+ */
+
 /**
  * A settings to load a stub-elements.
  * @typedef {Object} OPT_ldstubs
@@ -24,19 +29,24 @@ const {
  */
 
 /**
- * A stub-elements description list.
- * @typedef {Object} OBJ_stubEList
- * @property {Array} items - array of `name`-`element` pairs
+ * A stub-elements list descriptor
+ * @typedef {Object} IStubEListDesc
+ * @property {pairOfNameAndElement[]} items - array of `name`-`element` pairs
  * @property {string} [defaultItem] - a default element name
  */
 
 /**
- * A an options set for a `THtmlStubItemsSet`-class constructor
- * @typedef {Object} OPT_stubconsett
- * @property {(any[])} items - array of `name`-`element` pairs
+ * A set of options for a `THtmlStubItemsSet`-class constructor
+ * @typedef {Object} IStubItemsSetOptions
+ * @property {pairOfNameAndElement[]} items - array of `name`-`element` pairs
  * @property {string} [defaultItem] - a default element name
  * @property {boolean} [force=false] - run in a force mode
  */
+/** 
+ * A virtual constant meant for support jsdoc notation:
+ * @type {IStubItemsSetOptions}
+ */
+module.exports.IStubItemsSetOptions = { items: [] };
 
 /**
  * @classdesc This class implements an interface of a stub-items set
@@ -53,7 +63,7 @@ class THtmlStubItemsSet {
   /**
    * Creates an instance of a stub-items set
    * @param {HTMLElement} host - host element
-   * @param {(any[]|OPT_stubconsett|OBJ_stubEList)} [opt] - options
+   * @param {pairOfNameAndElement[]|IStubEListDesc|IStubItemsSetOptions} [opt] - options
    * @todo [since v0.0.26] use of an `array`-type as a value of an `opt` is deprecated
    */
   constructor(host, opt) {
@@ -62,7 +72,7 @@ class THtmlStubItemsSet {
     this.#_defItem = '';
     this.#_shownItem = null;
     if (isObject(opt)) {
-      /** @type {(OPT_stubconsett|OBJ_stubEList)} */
+      /** @type {IStubItemsSetOptions} */
       const obj = isArray(opt) ? { items: opt } : opt;
       const { items, defaultItem, force } = obj;
       this.loadItems({
@@ -205,9 +215,12 @@ class THtmlStubItemsSet {
    */
   showItem(name) {
     const item = this.getItem(name);
-    const isSUCCEED = this.#_host && item ? true : false;
-    if (isSUCCEED) this.#_host.append(item);
-    return isSUCCEED;
+    let isSucceed = false;
+    if (this.#_host && item) {
+      this.#_host.append(item);
+      isSucceed = true;
+    };
+    return isSucceed;
   }
 
   /**
@@ -225,9 +238,12 @@ class THtmlStubItemsSet {
    */
   hideItem(name) {
     const item = this.getItem(name);
-    const isSUCCEED = this.#_host && item ? true : false;
-    if (isSUCCEED && this.#_host.contains(item)) item.remove();
-    return isSUCCEED;
+    let isSucceed =  false;
+    if (this.#_host && item && this.#_host.contains(item)) {
+      isSucceed =  true;
+      item.remove();
+    };
+    return isSucceed;
   }
 
   /**
@@ -240,14 +256,15 @@ class THtmlStubItemsSet {
 
   /**
    * Adds an items to an instance members.
-   * @param {(Array|OBJ_stubEList)} data - an array of entries or special object
-   * @param {(boolean|OPT_ldstubs)} [opt] - an options
+   * @param {pairOfNameAndElement[]|IStubEListDesc} data - an array of entries or special object
+   * @param {boolean|OPT_ldstubs} [opt] - an options
    * @returns {number}
    * @todo [since 0.0.25] deprecate use of `opt` as `boolean`
    * @todo [since v0.0.26] for `OPT_ldstubs` a `defaultItem`-option deprecated
+   * @todo [since 0.0.32] deprecate use of `data` as `array`
    */
   loadItems(data, opt) {
-    /** @type {OBJ_stubEList} */
+    /** @type {IStubEListDesc} */
     let {
       items,
       defaultItem,
@@ -280,4 +297,4 @@ class THtmlStubItemsSet {
   }
 
 };
-exports.THtmlStubItemsSet = THtmlStubItemsSet;
+module.exports.THtmlStubItemsSet = THtmlStubItemsSet;

package/lib/mod-hfunc.d.ts

@@ -0,0 +1,18 @@
+export type IClickEventInfo = {
+    /**
+     * - some target element
+     */
+    item: object | null;
+    /**
+     * - reflects a current click count
+     */
+    onClickNum: number;
+};
+
+/**
+ * @function readOnClickEventInfo
+ * @param {UIEvent} e - event
+ * @returns {IClickEventInfo}
+ * @inner
+ */
+export function readOnClickEventInfo(e: UIEvent): IClickEventInfo;

package/lib/mod-hfunc.js

@@ -1,4 +1,4 @@
-// [v0.1.067-20260417]
+// [v0.1.068-20260422]
 
 // === module init block ===
 
@@ -6,10 +6,18 @@
 
 // === module main block ===
 
+/**
+ * 
+ * @typedef {Object} IClickEventInfo
+ * @property {?object} item - some target element
+ * @property {number} onClickNum - reflects a current click count
+ * @inner
+ */
+
 /**
  * @function readOnClickEventInfo
- * @param {Event} e
- * @returns {object}
+ * @param {UIEvent} e - event
+ * @returns {IClickEventInfo}
  * @inner
  */
 function readOnClickEventInfo(e) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cntwg/html-ctrls-lists",
-  "version": "0.0.31",
+  "version": "0.0.32",
   "description": "An HTML-form component: lists",
   "author": "ygracs <cs70th-om@rambler.ru>",
   "license": "MIT",
@@ -14,35 +14,40 @@
     "component"
   ],
   "main": "./index.js",
+  "types": "./index.d.ts",
   "files": [
     "doc/*.md",
     "lib/lists-stubs.js",
     "lib/lists-btn.js",
     "lib/list.js",
     "lib/mod-hfunc.js",
+    "lib/*.d.ts",
     "index.js",
+    "index.d.ts",
     "CHANGELOG.md"
   ],
   "scripts": {
     "test": "jest",
     "build-doc-md": "jsdoc2md",
-    "build-doc-html": "jsdoc"
+    "build-doc-html": "jsdoc",
+    "gen-dts": "npx -p typescript tsc"
   },
   "imports": {
     "#lib/*": "./lib/*",
     "#test-dir/*": "./__test__/*"
   },
   "dependencies": {
-    "@cntwg/html-ctrls-buttons": "~0.1.0",
+    "@cntwg/html-ctrls-buttons": "~0.1.1",
     "@cntwg/html-helper": "~0.1.3",
     "@ygracs/bsfoc-lib-js": "~0.3.4",
-    "@ygracs/lists-lib-js": "~0.2.0"
+    "@ygracs/lists-lib-js": "~0.2.1"
   },
   "devDependencies": {
     "@ygracs/test-helper": "~0.0.2-b",
     "jest": "^30.3.0",
     "jest-environment-jsdom": "^30.3.0",
     "jsdoc-to-markdown": "^9.1.3",
-    "minimist": "^1.2.8"
+    "minimist": "^1.2.8",
+    "typescript": "~5.9.3"
   }
 }