@cntwg/html-ctrls-lists 0.0.29 → 0.0.31

package/CHANGELOG.md

@@ -1,3 +1,24 @@
+#### *v0.0.31*
+
+Pre-release version.
+
+> - update `html-ctrls-list.md`;
+> - update dependency on `@ygracs/lists-lib-js` module to v0.2.0;
+> - update dependency on `@cntwg/html-helper` module to v0.1.3;
+> - update dependency on `@cntwg/html-ctrls-buttons` module to v0.1.0;
+> - (THtmlItemsListContainer) add method: `checkIndex`, `tryIndex`;
+> - (THtmlItemsListContainer) deprecate method: `chkIndex`, `chkIndexEx`;
+> - some fixes.
+
+#### *v0.0.30*
+
+Pre-release version.
+
+> - update dependency on `@ygracs/bsfoc-lib-js` module to v0.3.4;
+> - update dependency on `@ygracs/lists-lib-js` module to v0.1.2;
+> - update dependency on `@cntwg/html-helper` module to v0.1.2;
+> - update dependency on `@cntwg/html-ctrls-buttons` module to v0.0.30.
+
 #### *v0.0.29*
 
 Pre-release version.

package/doc/html-ctrls-list.md

@@ -1,23 +1,35 @@
->|***rev.*:**|0.1.24|
+>|***rev.*:**|0.1.25|
 >|:---|---:|
->|date:|2025-05-05|
+>|date:|2026-04-18|
 
 ## Introduction
 
 This paper describes a classes provided by `list.js`, `lists-stubs.js` and `lists-btn.js` of `html-ctrls` sub-module.
 
-## Module classes
+## Content
+
+- Classes
+    - <a href="#THtmlItemsListContainer">THtmlItemsListContainer</a>
+    - <a href="#THtmlItemsListController">THtmlItemsListController</a>
+    - <a href="#THtmlListButtonsController">THtmlListButtonsController</a>
+    - <a href="#THtmlStubItemsSet">THtmlStubItemsSet</a>
+
+### Base type definitions
+
+This section contains some definitions for a general types of the objects (e.g. options set) that frequently used in a function or a class method descriptions.
+
+### Module classes
 
 <a name="THtmlItemsListContainer"></a>
-### **THtmlItemsListContainer**
+#### **THtmlItemsListContainer**
 
 This class provide a base container useful when dealing with a list elements placed on an HTML-form.
 
-#### class constructor
+##### class constructor
 
 The class constructor creates a new instance of the class.
 
-##### constructor parameters
+###### constructor parameters
 
 The class constructor receives a parameters listed below:
 
@@ -26,7 +38,7 @@ The class constructor receives a parameters listed below:
 | `host` | `HTMLElement` | `undefined` | points to a host element which holds a list items |
 | `options` | `object` | --- | contains a container settings |
 
-##### `options` parameter
+###### ***`options` parameter***
 
 The `options` structure has listed below:
 
@@ -36,85 +48,103 @@ The `options` structure has listed below:
 | `markCurrentItem` | `boolean` | `false` |alters behavior of the `setCurIndex` class method. If set to `true`, the item which was added to a container members will be automatically marked as current |
 | `itemBaseClassID` | `string`, `string[]` | --- | alters behavior of the `addItem` class method. It accepts value of a string or an array of strings. For more see description of an `addItem` method |
 
-#### class properties
+##### class properties
 
 <a name="THtmlItemsListContainer+count"></a>
-##### **count**
+###### **count**
 
 | property type | read only | description |
 |---|---|:---|
 | `number` | yes | contains a quantity of the elements the container holds |
 
 <a name="THtmlItemsListContainer+curIndex"></a>
-##### **curIndex**
+###### **curIndex**
 
 | property type | read only | description |
 |---|---|:---|
 | `number` | yes | represents an index of the current element |
 
 <a name="THtmlItemsListContainer+minIndex"></a>
-##### **minIndex**
+###### **minIndex**
 
 | property type | read only | description |
 |---|---|:---|
 | `number` | yes | represents a minimum possible index for an element inside the container |
 
 <a name="THtmlItemsListContainer+maxIndex"></a>
-##### **maxIndex**
+###### **maxIndex**
 
 | property type | read only | description |
 |---|---|:---|
 | `number` | yes | represents a maximum possible index for an element inside the container |
 
 <a name="THtmlItemsListContainer+prevIndex"></a>
-##### **prevIndex**
+###### **prevIndex**
 
 | property type | read only | description |
 |---|---|:---|
 | `number` | yes | represents an index of the previous element before the current |
 
 <a name="THtmlItemsListContainer+nextIndex"></a>
-##### **nextIndex**
+###### **nextIndex**
 
 | property type | read only | description |
 |---|---|:---|
 | `number` | yes | represents an index of the next element after the current |
 
 <a name="THtmlItemsListContainer+curItem"></a>
-##### **curItem**
+###### **curItem**
 
 | property type | read only | description |
 |---|---|:---|
 | `?HTMLElement` | yes | represents an element addressed by the `curIndex` |
 
-#### class methods
+##### class methods
 
 <a name="THtmlItemsListContainer+clear"></a>
-##### **clear()** => `void`
+###### **clear()** => `void`
 
 This method deletes all items that holds by the container.
 
 <a name="THtmlItemsListContainer+isEmpty"></a>
-##### **isEmpty()** => `boolean`
+###### **isEmpty()** => `boolean`
 
 This method returns `true` if the container has no items.
 
 <a name="THtmlItemsListContainer+isNotEmpty"></a>
-##### **isNotEmpty()** => `boolean`
+###### **isNotEmpty()** => `boolean`
 
 This method returns `true` if the container has at least one item.
 
 <a name="THtmlItemsListContainer+chkIndex"></a>
-##### **chkIndex(value)** => `boolean`
+###### **chkIndex(value)** => `boolean`
+
+> WARNING: \[since `v0.0.3x`] this method deprecated (*use [`checkIndex`](#THtmlItemsListContainer+checkIndex) method instead*).
+
+<a name="THtmlItemsListContainer+checkIndex"></a>
+###### **checkIndex(value)** => `boolean`
+
+> since: \[`v0.0.3x`]
+
+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.
+
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `value` | `number` or `string` | --- | a value to be verified |
+
+<a name="THtmlItemsListContainer+tryIndex"></a>
+###### **tryIndex(value)** => `number`
 
-This method returns `true` if a given `value` represents a valid index within the range of the list.
+> since: \[`v0.0.3x`]
+
+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.
 
 | parameter name | value type | default value | description |
 |:---|---|---:|:---|
 | `value` | `any` | --- | a value to be verified |
 
 <a name="THtmlItemsListContainer+chkIndexEx"></a>
-##### **chkIndexEx(value\[, mode])** => `boolean`\|`number`
+###### **chkIndexEx(value\[, mode])** => `boolean`\|`number`
 
 This method is similar to a `chkIndex` methods but receives a `mode` parameter which allow to choose what a type of the result the method returns.
 
@@ -129,8 +159,10 @@ 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*).
+
 <a name="THtmlItemsListContainer+srchIndex"></a>
-##### **srchIndex(item)** => `number`
+###### **srchIndex(item)** => `number`
 
 This method tries to find a given item in the list and if it is found returns its index.
 
@@ -139,7 +171,7 @@ This method tries to find a given item in the list and if it is found returns it
 | `item` | `?HTMLElement` | --- | an element to search |
 
 <a name="THtmlItemsListContainer+srchIndexByAttr"></a>
-##### **srchIndexByAttr(name, value)** => `number`
+###### **srchIndexByAttr(name, value)** => `number`
 
 This method tries to find an item that has an attribute with a given `name` and `value` in the list and if it is found its index is returned.
 
@@ -153,7 +185,7 @@ The `value` can be a `boolean`, `number` or a `string`. If it is not given the e
 > Note: In case when a `value` is an empty string the method will accept any item with an attribute which name is equal to a given `name` regardless of a value such attribute has.
 
 <a name="THtmlItemsListContainer+srchIndexByID"></a>
-##### **srchIndexByID(value)** => `number`
+###### **srchIndexByID(value)** => `number`
 
 This method tries to find an item by its `ID`-attribute in the list and if it is found returns its index (*see description of `srchIndexByAttr` method for details how a `value` parameter is used*).
 
@@ -162,7 +194,7 @@ This method tries to find an item by its `ID`-attribute in the list and if it is
 | `value` | `string` | --- | an ID value |
 
 <a name="THtmlItemsListContainer+setCurIndex"></a>
-##### **setCurIndex(index)** => `boolean`
+###### **setCurIndex(index)** => `boolean`
 
 This method sets a current item index in the list. If succeed `true` is returned.
 
@@ -171,12 +203,12 @@ This method sets a current item index in the list. If succeed `true` is returned
 | `index` | `number`, `string` | --- | an element index |
 
 <a name="THtmlItemsListContainer+rstCurIndex"></a>
-##### **rstCurIndex()** => `void`
+###### **rstCurIndex()** => `void`
 
 This method resets a current element index in the list.
 
 <a name="THtmlItemsListContainer+getItem"></a>
-##### **getItem(index)** => `?HTMLElement`
+###### **getItem(index)** => `?HTMLElement`
 
 This method returns an element addressed by a given `index`.
 
@@ -185,7 +217,7 @@ This method returns an element addressed by a given `index`.
 | `index` | `number`, `string` | --- | an element index |
 
 <a name="THtmlItemsListContainer+getItemByAttr"></a>
-##### **getItemByAttr(name, value)** => `?HTMLElement`
+###### **getItemByAttr(name, value)** => `?HTMLElement`
 
 This method tries to find an item by its given attribute in the list and if found returns it (*see description of `srchIndexByAttr` method for details how a `value` parameter is used*).
 
@@ -195,7 +227,7 @@ This method tries to find an item by its given attribute in the list and if foun
 | `value` | `any` | --- | an attribute value |
 
 <a name="THtmlItemsListContainer+getItemByID"></a>
-##### **getItemByID(value)** => `?HTMLElement`
+###### **getItemByID(value)** => `?HTMLElement`
 
 This method tries to find an item by its `ID`-attribute in the list and if found returns it (*see description of `srchIndexByAttr` method for details how a `value` parameter is used*).
 
@@ -204,7 +236,7 @@ This method tries to find an item by its `ID`-attribute in the list and if found
 | `value` | `string` | --- | an ID value |
 
 <a name="THtmlItemsListContainer+addItem"></a>
-##### **addItem(item\[, options])** => `number`
+###### **addItem(item\[, options])** => `number`
 
 This method adds a given item to a container members and if succeed returns its index.
 
@@ -218,7 +250,7 @@ If `options` parameter is given and is set to `true`, in case of success, the `c
 If `itemBaseClassID` option of the container is set, the method will applied a value given by this option as a `class` attribute of an item which was successfully added.
 
 <a name="THtmlItemsListContainer+delItem"></a>
-##### **delItem(index\[, options\[, optEx]])** => `boolean`
+###### **delItem(index\[, options\[, optEx]])** => `boolean`
 
 This method deletes an item addressed by the given `index` from a container members and if succeed `true` is returned.
 
@@ -231,7 +263,7 @@ This method deletes an item addressed by the given `index` from a container memb
 If `options` parameter is set to `true` (a default value), the `curIndex` property is adjusted by the method. If it is set to `false` the `curIndex` property is not adjusted before a value of the property exited out of the list indexes range that caused the property to be reset. In case the `options` is not given or is not a type of a `boolean`, its receives the default value.
 
 <a name="THtmlItemsListContainer+selectItem"></a>
-##### **selectItem(index\[, options])** => `boolean`
+###### **selectItem(index\[, options])** => `boolean`
 
 This method selects an item addressed by an `index` and if succeed `true` is returned.
 
@@ -243,7 +275,7 @@ This method selects an item addressed by an `index` and if succeed `true` is ret
 If `options` parameter is given and is set to `true`, in case of success, the `curIndex` property is adjusted by the method.
 
 <a name="THtmlItemsListContainer+unselectItem"></a>
-##### **unselectItem(index)** => `boolean`
+###### **unselectItem(index)** => `boolean`
 
 This method unselects an item addressed by an `index` and if succeed `true` is returned.
 
@@ -252,7 +284,7 @@ This method unselects an item addressed by an `index` and if succeed `true` is r
 | `index` | `number`, `string` | --- | an element index |
 
 <a name="THtmlItemsListContainer+hideItem"></a>
-##### **hideItem(index)** => `boolean`
+###### **hideItem(index)** => `boolean`
 
 This method hides an item addressed by an `index` and if succeed `true` is returned.
 
@@ -261,7 +293,7 @@ This method hides an item addressed by an `index` and if succeed `true` is retur
 | `index` | `number`, `string` | --- | an element index |
 
 <a name="THtmlItemsListContainer+showItem"></a>
-##### **showItem(index)** => `boolean`
+###### **showItem(index)** => `boolean`
 
 This method shows an item addressed by an `index` and if succeed `true` is returned.
 
@@ -270,7 +302,7 @@ This method shows an item addressed by an `index` and if succeed `true` is retur
 | `index` | `number`, `string` | --- | an element index |
 
 <a name="THtmlItemsListContainer+isSelectedItem"></a>
-##### **isSelectedItem(index)** => `boolean`
+###### **isSelectedItem(index)** => `boolean`
 
 This method checks whether or not an item addressed by an `index` is selected and if so `true` is returned.
 
@@ -279,7 +311,7 @@ This method checks whether or not an item addressed by an `index` is selected an
 | `index` | `number`, `string` | --- | an element index |
 
 <a name="THtmlItemsListContainer+isHiddenItem"></a>
-##### **isHiddenItem(index)** => `boolean`
+###### **isHiddenItem(index)** => `boolean`
 
 This method checks whether or not an item addressed by an `index` is hidden and if so `true` is returned.
 
@@ -288,15 +320,15 @@ This method checks whether or not an item addressed by an `index` is hidden and
 | `index` | `number`, `string` | --- | an element index |
 
 <a name="THtmlItemsListController"></a>
-### **THtmlItemsListController**
+#### **THtmlItemsListController**
 
 This class implements a controller that provide mechanism for managing a list container and its elements placed on an HTML-form.
 
-#### class constructor
+##### class constructor
 
 The class constructor creates a new instance of the class.
 
-##### constructor parameters
+###### constructor parameters
 
 The class constructor receives a parameters listed below:
 
@@ -305,7 +337,7 @@ The class constructor receives a parameters listed below:
 | `host` | `HTMLElement` | `undefined` |points to a host element which holds a list items |
 | `options` | `object` | --- | contains a set of a settings for a container |
 
-##### `options` parameter
+###### ***`options` parameter***
 
 The `options` structure has listed below:
 
@@ -318,116 +350,134 @@ The `options` structure has listed below:
 | `allowGroupSelection` | `boolean` | `false` | if set the more than one element can be selected in the list |
 | `allowSelectionLocks` | `boolean` | `false` | \<*reserved, experimental*> |
 
-#### class properties
+##### class properties
 
 <a name="THtmlItemsListController+count"></a>
-##### **count**
+###### **count**
 
 | property type | read only | description |
 |---|---|:---|
 | `number` | yes | contains a quantity of the elements the container holds |
 
 <a name="THtmlItemsListController+curIndex"></a>
-##### **curIndex**
+###### **curIndex**
 
 | property type | read only | description |
 |---|---|:---|
 | `number` | yes | represents an index of the current element |
 
 <a name="THtmlItemsListController+minIndex"></a>
-##### **minIndex**
+###### **minIndex**
 
 | property type | read only | description |
 |---|---|:---|
 | `number` | yes | represents a minimum possible index for an element inside the container |
 
 <a name="THtmlItemsListController+maxIndex"></a>
-##### **maxIndex**
+###### **maxIndex**
 
 | property type | read only | description |
 |---|---|:---|
 | `number` | yes | represents a maximum possible index for an element inside the container |
 
 <a name="THtmlItemsListController+prevIndex"></a>
-##### **prevIndex**
+###### **prevIndex**
 
 | property type | read only | description |
 |---|---|:---|
 | `number` | yes | represents an index of the previous element before the current |
 
 <a name="THtmlItemsListController+nextIndex"></a>
-##### **nextIndex**
+###### **nextIndex**
 
 | property type | read only | description |
 |---|---|:---|
 | `number` | yes | represents an index of the next element after the current |
 
 <a name="THtmlItemsListController+curItem"></a>
-##### **curItem**
+###### **curItem**
 
 | property type | read only | description |
 |---|---|:---|
 | `?HTMLElement` | yes | represents an element addressed by the `curIndex` |
 
 <a name="THtmlItemsListController+isSelectionLocked"></a>
-##### **isSelectionLocked**
+###### **isSelectionLocked**
 
 | property type | read only | description |
 |---|---|:---|
 | `boolean` | yes | returns `true` if selections of an items is not allowed |
 
 <a name="THtmlItemsListController+SelectedItems"></a>
-##### **SelectedItems**
+###### **SelectedItems**
 
 | property type | read only | description |
 |---|---|:---|
 | `HTMLElement[]` | yes | returns an array of the selected elements |
 
 <a name="THtmlItemsListController+StubItems"></a>
-##### **StubItems**
+###### **StubItems**
 
 | property type | read only | description |
 |---|---|:---|
 | `THtmlStubItemsSet` | yes | returns a `THtmlStubItemsSet` instance |
 
-#### class methods
+##### class methods
 
 <a name="THtmlItemsListController+clear"></a>
-##### **clear()** => `void`
+###### **clear()** => `void`
 
 This method deletes all items that is hold by the list.
 
 <a name="THtmlItemsListController+lockItemsSelection"></a>
-##### **lockItemsSelection()** => `void`
+###### **lockItemsSelection()** => `void`
 
 This method blocks a selection of the items in the list.
 
 <a name="THtmlItemsListController+unlockItemsSelection"></a>
-##### **unlockItemsSelection()** => `void`
+###### **unlockItemsSelection()** => `void`
 
 This method allows a selection of the items in the list.
 
-<a name="THtmlItemsListContainer+isEmpty"></a>
-##### **isEmpty()** => `boolean`
+<a name="THtmlItemsListController+isEmpty"></a>
+###### **isEmpty()** => `boolean`
 
 This method returns `true` if the list has no items.
 
-<a name="THtmlItemsListContainer+isNotEmpty"></a>
-##### **isNotEmpty()** => `boolean`
+<a name="THtmlItemsListController+isNotEmpty"></a>
+###### **isNotEmpty()** => `boolean`
 
 This method returns `true` if the list has at least one item.
 
-<a name="THtmlItemsListContainer+chkIndex"></a>
-##### **chkIndex(value)** => `boolean`
+<a name="THtmlItemsListController+chkIndex"></a>
+###### **chkIndex(value)** => `boolean`
+
+> WARNING: \[since `v0.0.3x`] this method deprecated (*use [`checkIndex`](#THtmlItemsListController+checkIndex) method instead*).
 
-This method returns `true` if a given value represent a valid index within the range of the list.
+<a name="THtmlItemsListController+checkIndex"></a>
+###### **checkIndex(value)** => `boolean`
+
+> since: \[`v0.0.3x`]
+
+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.
+
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `value` | `number` or `string` | --- | a value to be verified |
+
+<a name="THtmlItemsListController+tryIndex"></a>
+###### **tryIndex(value)** => `number`
+
+> since: \[`v0.0.3x`]
+
+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.
 
 | parameter name | value type | default value | description |
 |:---|---|---:|:---|
 | `value` | `any` | --- | a value to be verified |
 
-<a name="THtmlItemsListContainer+chkIndexEx"></a>
-##### **chkIndexEx(value\[, mode])** => `boolean`\|`number`
+<a name="THtmlItemsListController+chkIndexEx"></a>
+###### **chkIndexEx(value\[, mode])** => `boolean`\|`number`
 
 This method is similar to a `chkIndex` methods but receives a `mode` parameter which allow to choose what a type of the result the method returns.
 
@@ -440,8 +490,10 @@ 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.
 
-<a name="THtmlItemsListContainer+srchIndex"></a>
-##### **srchIndex(item)** => `number`
+> WARNING: \[since `v0.0.3x`] this method deprecated (*use [`checkIndex`](#THtmlItemsListController+checkIndex) or [`tryIndex`](#THtmlItemsListController+tryIndex) method instead*).
+
+<a name="THtmlItemsListController+srchIndex"></a>
+###### **srchIndex(item)** => `number`
 
 This method tries to find a given item in the list and if it is found returns its index.
 
@@ -449,8 +501,8 @@ This method tries to find a given item in the list and if it is found returns it
 |:---|---|---:|:---|
 | `item` | `?HTMLElement` | --- | an element to search |
 
-<a name="THtmlItemsListContainer+srchIndexByAttr"></a>
-##### **srchIndexByAttr(name, value)** => `number`
+<a name="THtmlItemsListController+srchIndexByAttr"></a>
+###### **srchIndexByAttr(name, value)** => `number`
 
 This method tries to find an item by its given attribute in the list and if it is found returns its index.
 
@@ -459,8 +511,8 @@ This method tries to find an item by its given attribute in the list and if it i
 | `name` | `string` | --- | an attribute name |
 | `value` | `any` | --- | an attribute value |
 
-<a name="THtmlItemsListContainer+srchIndexByID"></a>
-##### **srchIndexByID(value)** => `number`
+<a name="THtmlItemsListController+srchIndexByID"></a>
+###### **srchIndexByID(value)** => `number`
 
 This method tries to find an item by its `ID`-attribute in the list and if it is found returns its index.
 
@@ -469,7 +521,7 @@ This method tries to find an item by its `ID`-attribute in the list and if it is
 | `value` | `string` | --- | an ID value |
 
 <a name="THtmlItemsListController+setCurIndex"></a>
-##### **setCurIndex(index)** => `boolean`
+###### **setCurIndex(index)** => `boolean`
 
 This method sets a current item index in the list. If succeed `true` is returned.
 
@@ -478,12 +530,12 @@ This method sets a current item index in the list. If succeed `true` is returned
 | `index` | `number`, `string` | --- | an element index |
 
 <a name="THtmlItemsListController+rstCurIndex"></a>
-##### **rstCurIndex()** => `void`
+###### **rstCurIndex()** => `void`
 
 This method resets a current item index in the list.
 
-<a name="THtmlItemsListContainer+getItem"></a>
-##### **getItem(index)** => `?HTMLElement`
+<a name="THtmlItemsListController+getItem"></a>
+###### **getItem(index)** => `?HTMLElement`
 
 This method returns an item addressed by a given index.
 
@@ -491,8 +543,8 @@ This method returns an item addressed by a given index.
 |:---|---|---:|:---|
 | `index` | `number`, `string` | --- | an element index |
 
-<a name="THtmlItemsListContainer+getItemByAttr"></a>
-##### **getItemByAttr(name, value)** => `?HTMLElement`
+<a name="THtmlItemsListController+getItemByAttr"></a>
+###### **getItemByAttr(name, value)** => `?HTMLElement`
 
 This method tries to find an item by its given attribute in the list and if found returns it.
 
@@ -501,8 +553,8 @@ This method tries to find an item by its given attribute in the list and if foun
 | `name` | `string` | --- | an attribute name |
 | `value` | `any` | --- | an attribute value |
 
-<a name="THtmlItemsListContainer+getItemByID"></a>
-##### **getItemByID(value)** => `?HTMLElement`
+<a name="THtmlItemsListController+getItemByID"></a>
+###### **getItemByID(value)** => `?HTMLElement`
 
 This method tries to find an item by its `ID`-attribute in the list and if found returns it.
 
@@ -511,7 +563,7 @@ This method tries to find an item by its `ID`-attribute in the list and if found
 | `value` | `string` | --- | an ID value |
 
 <a name="THtmlItemsListController+addItem"></a>
-##### **addItem(item\[, options])** => `number`
+###### **addItem(item\[, options])** => `number`
 
 This method adds a given item to a list members and if succeed returns its index.
 
@@ -521,7 +573,7 @@ This method adds a given item to a list members and if succeed returns its index
 | `options` | `boolean` | `false` | a flag to switch mode |
 
 <a name="THtmlItemsListController+delItem"></a>
-##### **delItem(index\[, options])** => `boolean`
+###### **delItem(index\[, options])** => `boolean`
 
 This method deletes an item addressed by `index` from a list members and if succeed `true` is returned.
 
@@ -531,7 +583,7 @@ This method deletes an item addressed by `index` from a list members and if succ
 | `options` | `boolean` | `true` | a flag to switch mode |
 
 <a name="THtmlItemsListController+selectItem"></a>
-##### **selectItem(index\[, options])** => `boolean`
+###### **selectItem(index\[, options])** => `boolean`
 
 This method selects an item addressed by an `index` and if succeed `true` is returned.
 
@@ -541,7 +593,7 @@ This method selects an item addressed by an `index` and if succeed `true` is ret
 | `options` | `boolean` | `false` | a flag to switch mode |
 
 <a name="THtmlItemsListController+unselectItem"></a>
-##### **unselectItem(index)** => `boolean`
+###### **unselectItem(index)** => `boolean`
 
 This method unselects an item addressed by an `index` and if succeed `true` is returned.
 
@@ -550,12 +602,12 @@ This method unselects an item addressed by an `index` and if succeed `true` is r
 | `index` | `number`, `string` | --- | an element index |
 
 <a name="THtmlItemsListController+hideItem"></a>
-##### **hideItem(index)** => `boolean`
+###### **hideItem(index)** => `boolean`
 
 This method hides an item addressed by an `index` and if succeed `true` is returned.
 
 <a name="THtmlItemsListController+showItem"></a>
-##### **showItem(index)** => `boolean`
+###### **showItem(index)** => `boolean`
 
 This method shows an item addressed by an `index` and if succeed `true` is returned.
 
@@ -563,8 +615,8 @@ This method shows an item addressed by an `index` and if succeed `true` is retur
 |:---|---|---:|:---|
 | `index` | `number`, `string` | --- | an element index |
 
-<a name="THtmlItemsListContainer+isSelectedItem"></a>
-##### **isSelectedItem(index)** => `boolean`
+<a name="THtmlItemsListController+isSelectedItem"></a>
+###### **isSelectedItem(index)** => `boolean`
 
 This method checks whether or not an item addressed by an `index` is selected and if so `true` is returned.
 
@@ -572,8 +624,8 @@ This method checks whether or not an item addressed by an `index` is selected an
 |:---|---|---:|:---|
 | `index` | `number`, `string` | --- | an element index |
 
-<a name="THtmlItemsListContainer+isHiddenItem"></a>
-##### **isHiddenItem(index)** => `boolean`
+<a name="THtmlItemsListController+isHiddenItem"></a>
+###### **isHiddenItem(index)** => `boolean`
 
 This method checks whether or not an item addressed by an `index` is hidden and if so `true` is returned.
 
@@ -582,7 +634,7 @@ This method checks whether or not an item addressed by an `index` is hidden and
 | `index` | `number`, `string` | --- | an element index |
 
 <a name="THtmlItemsListController+on"></a>
-##### **on(name, event)** => `void`
+###### **on(name, event)** => `void`
 
 This method sets event handler for the list event addressed by a `name` parameter.
 
@@ -593,7 +645,7 @@ This method sets event handler for the list event addressed by a `name` paramete
 
 > Note: for current implementation you can't reset or set new event handler (especially another one) if a handler with the same name exists already.
 
-#### class events
+##### class events
 
 The class generates the events listed in the table bellow:
 
@@ -610,15 +662,15 @@ The class generates the events listed in the table bellow:
 | `item-shown` | fired when an item was marked as non-hidden in the list |
 
 <a name="THtmlStubItemsSet"></a>
-### **THtmlStubItemsSet**
+#### **THtmlStubItemsSet**
 
 This class implements a controller that provide mechanism for managing a so-called "stub"-elements displayed inside an attached list container placed on an HTML-form.
 
-#### class constructor
+##### class constructor
 
 The class constructor creates a new instance of the class.
 
-##### constructor parameters
+###### constructor parameters
 
 The class constructor receives a parameters listed below:
 
@@ -629,7 +681,7 @@ The class constructor receives a parameters listed below:
 
 > \[!] NOTE: `[since v0.0.26]` a use of a `array` type as a value of an `options` are deprecated and will be dropped soon.
 
-##### `options` parameter
+###### ***`options` parameter***
 
 The `options` structure has listed below:
 
@@ -639,31 +691,31 @@ The `options` structure has listed below:
 | `defaultItem` | `string` | --- | if set it defines a name of the item used by default |
 | `force` | `boolean` | `false` | if set to `true`, the item which is already present will be replaced with a new one |
 
-#### class properties
+##### class properties
 
 <a name="THtmlStubItemsSet+count"></a>
-##### **count**
+###### **count**
 
 | property type | read only | description |
 |---|---|:---|
 | `number` | yes | contains a quantity of an elements which holds by the set |
 
 <a name="THtmlStubItemsSet+defItem"></a>
-##### **defItem**
+###### **defItem**
 
 | property type | read only | description |
 |---|---|:---|
 | `string` | no | defines an element name which is used by default |
 
-#### class methods
+##### class methods
 
 <a name="THtmlStubItemsSet+clear"></a>
-##### **clear()** => `void`
+###### **clear()** => `void`
 
 This class method deletes all items hold by the set.
 
 <a name="THtmlStubItemsSet+hasItem"></a>
-##### **hasItem(name)** => `boolean`
+###### **hasItem(name)** => `boolean`
 
 This class method returns `true` if an item named by `name` exists in the set and `false` if else.
 
@@ -672,12 +724,12 @@ This class method returns `true` if an item named by `name` exists in the set an
 | `name` | `string` | --- | an element name |
 
 <a name="THtmlStubItemsSet+hasItems"></a>
-##### **hasItems()** => `boolean`
+###### **hasItems()** => `boolean`
 
 This class method returns `true` if the set hold any items and `false` if not.
 
 <a name="THtmlStubItemsSet+getItem"></a>
-##### **getItem(name)** => `?HTMLElement`
+###### **getItem(name)** => `?HTMLElement`
 
 This class method returns an item named by `name` if it exists in the set and `null` if else.
 
@@ -686,7 +738,7 @@ This class method returns an item named by `name` if it exists in the set and `n
 | `name` | `string` | --- | an element name |
 
 <a name="THtmlStubItemsSet+addItem"></a>
-##### **addItem(name, item\[, options])** => `boolean`
+###### **addItem(name, item\[, options])** => `boolean`
 
 This class method tries to include a given `item` to a set members with a label given by `name` and if succeed returns `true`.
 
@@ -703,7 +755,7 @@ The `actForce` parameter if given alters the method behavior:
 - If parameter is not given or not of a `boolean` type its default value meant to be `false`.
 
 <a name="THtmlStubItemsSet+delItem"></a>
-##### **delItem(name)** => `boolean`
+###### **delItem(name)** => `boolean`
 
 This class method tries to delete item named by `name` from the set and if succeed `true` is returned.
 
@@ -712,7 +764,7 @@ This class method tries to delete item named by `name` from the set and if succe
 | `name` | `string` | --- | an element name |
 
 <a name="THtmlStubItemsSet+showItem"></a>
-##### **showItem(name)** => `boolean`
+###### **showItem(name)** => `boolean`
 
 This class method tries to make item named by `name` visible on HTML-form and if succeed `true` is returned.
 
@@ -721,7 +773,7 @@ This class method tries to make item named by `name` visible on HTML-form and if
 | `name` | `string` | --- | an element name |
 
 <a name="THtmlStubItemsSet+hideItem"></a>
-##### **hideItem(name)** => `boolean`
+###### **hideItem(name)** => `boolean`
 
 This class method tries to make item named by `name` invisible on HTML-form and if succeed `true` is returned.
 
@@ -730,7 +782,7 @@ This class method tries to make item named by `name` invisible on HTML-form and
 | `name` | `string` | --- | an element name |
 
 <a name="THtmlStubItemsSet+setDefItem"></a>
-##### **setDefItem(name)** => `boolean`
+###### **setDefItem(name)** => `boolean`
 
 This class method tries to set item named by `name` as a default item and if succeed `true` is returned.
 
@@ -739,22 +791,22 @@ This class method tries to set item named by `name` as a default item and if suc
 | `name` | `string` | --- | an element name |
 
 <a name="THtmlStubItemsSet+rstDefItem"></a>
-##### **rstDefItem()** => `void`
+###### **rstDefItem()** => `void`
 
 This class method resets a default item.
 
 <a name="THtmlStubItemsSet+showDefItem"></a>
-##### **showDefItem()** => `boolean`
+###### **showDefItem()** => `boolean`
 
 This class method is similar to `showItem` method but is performed on a default item.
 
 <a name="THtmlStubItemsSet+hideDefItem"></a>
-##### **hideDefItem()** => `boolean`
+###### **hideDefItem()** => `boolean`
 
 This class method is similar to `hideItem` method but is performed on a default item.
 
 <a name="THtmlStubItemsSet+loadItems"></a>
-##### **loadItems(data\[, options])** => `number`
+###### **loadItems(data\[, options])** => `number`
 
 This class methods loads an items given by `list` in the set and returned quantity of how many items have been processed successfully.
 
@@ -795,15 +847,15 @@ If the `options` parameter is an `object` that contains the following set of par
 If the `options` parameter is a `boolean` value it treats as a `options.useClear` option.
 
 <a name="THtmlListButtonsController"></a>
-### **THtmlListButtonsController**
+#### **THtmlListButtonsController**
 
 This class provides a buttons controller to use with a list components to performs actions for list elements selection.
 
-#### class constructor
+##### class constructor
 
 The class constructor creates a new instance of the class.
 
-##### constructor parameters
+###### constructor parameters
 
 The class constructor receives an `options` parameter which structure has listed below:
 
@@ -814,46 +866,46 @@ The class constructor receives an `options` parameter which structure has listed
 | `btnNext` | `?HTMLElement` | `undefined` | defines an HTML-button which will select the next element |
 | `btnLast` | `?HTMLElement` | `undefined` | defines an HTML-button which will select the last element |
 
-#### class properties
+##### class properties
 
 This class has none.
 
-#### class methods
+##### class methods
 
 <a name="THtmlListButtonsController+disableAll"></a>
-##### **disableAll()** => `void`
+###### **disableAll()** => `void`
 
 This method disables all buttons that holds by the controller.
 
 <a name="THtmlListButtonsController+disableBkwd"></a>
-##### **disableBkwd()** => `void`
+###### **disableBkwd()** => `void`
 
 This method disables all buttons in *'move backward'* group (*i.e. `btnFirst` and `btnPrev`*) that holds by the controller.
 
 <a name="THtmlListButtonsController+disableFrwd"></a>
-##### **disableFrwd()** => `void`
+###### **disableFrwd()** => `void`
 
 This method disables all buttons in *'move forward'* group (*i.e. `btnNext` and `btnLast`*) that holds by the controller.
 
 <a name="THtmlListButtonsController+enableAll"></a>
-##### **enableAll()** => `void`
+###### **enableAll()** => `void`
 
 This method enables all buttons that holds by the controller.
 
 <a name="THtmlListButtonsController+enableBkwd"></a>
-##### **enableBkwd()** => `void`
+###### **enableBkwd()** => `void`
 
 This method enables all buttons in *'move backward'* group (*i.e. `btnFirst` and `btnPrev`*) that holds by the controller.
 
 <a name="THtmlListButtonsController+enableFrwd"></a>
-##### **enableFrwd()** => `void`
+###### **enableFrwd()** => `void`
 
 This method enables all buttons in *'move forward'* group (*i.e. `btnNext` and `btnLast`*) that holds by the controller.
 
-#### class methods (*special*)
+##### class methods (*special*)
 
 <a name="THtmlListButtonsController+on"></a>
-##### **on(name, event)** => `void`
+###### **on(name, event)** => `void`
 
 This method sets event handler addressed by a `name` parameter.
 
@@ -864,7 +916,7 @@ This method sets event handler addressed by a `name` parameter.
 
 > Note: for current implementation you can't reset or set new event handler (*especially another one*) if a handler with the same name exists already.
 
-#### class events
+##### class events
 
 The class generates the events listed in the table bellow:
 

package/index.js

@@ -1,9 +1,10 @@
-// [v0.1.030-20250831]
+// [v0.1.031-20260309]
 
 // === module init block ===
 
-const html_list = require('./lib/list.js');
-const html_list_btn = require('./lib/lists-btn.js');
+const list = require('./lib/list');
+const btn = require('./lib/lists-btn');
+const stubs = require('./lib/lists-stubs');
 
 // === module inner block ===
 
@@ -11,10 +12,11 @@ const html_list_btn = require('./lib/lists-btn.js');
 
 // === module exports block ===
 
-module.exports.THtmlStubItemsSet = html_list.THtmlStubItemsSet;
-module.exports.THtmlItemsListContainer = html_list.THtmlItemsListContainer;
-module.exports.THtmlItemsListController = html_list.THtmlItemsListController;
+module.exports.THtmlStubItemsSet = stubs.THtmlStubItemsSet;
 
-module.exports.BTS_DEF_GROUP_NAME = html_list_btn.BTS_DEF_GROUP_NAME;
+module.exports.THtmlItemsListContainer = list.THtmlItemsListContainer;
+module.exports.THtmlItemsListController = list.THtmlItemsListController;
 
-module.exports.THtmlListButtonsController = html_list_btn.THtmlListButtonsController;
+module.exports.BTS_DEF_GROUP_NAME = btn.BTS_DEF_GROUP_NAME;
+
+module.exports.THtmlListButtonsController = btn.THtmlListButtonsController;

package/lib/list.js

@@ -1,4 +1,4 @@
-// [v0.1.075-20260110]
+// [v0.1.079-20260416]
 
 // === module init block ===
 
@@ -68,22 +68,10 @@ function srchListElementByAttr(list, name, value = '') {
 
 // === module main block ===
 
-/***
- * (* constant definitions *)
- */
-
 const ILC_SMODE_DEF = 0;
 const ILC_SMODE_SHFT = 1;
 const ILC_SMODE_CTRL = 2;
 
-/***
- * (* function definitions *)
- */
-
-/***
- * (* class definitions *)
- */
-
 /**
  * An options set for `THtmlItemsListContainer`-class
  * @typedef {Object} OPT_hlconsett
@@ -265,23 +253,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.3x] 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.3x
+   * @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)}
+   * @returns {boolean|number}
    * @see TItemsListEx.chkIndexEx
+   * @todo \[since v0.0.3x] 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.3x
+   * @param {any} value - value to evaluate
+   * @returns {number}
+   */
+  tryIndex(value) {
+    return this.#_items.tryIndex(value);
   }
 
   /**
@@ -495,6 +511,7 @@ class THtmlItemsListContainer {
   }
 
 };
+exports.THtmlItemsListContainer = THtmlItemsListContainer;
 
 /**
  * A an options set for a `THtmlStubItemsSet`-class constructor
@@ -1129,9 +1146,8 @@ class THtmlItemsListController extends THtmlItemsListContainer {
   }
 
 };
+exports.THtmlItemsListController = THtmlItemsListController;
 
 // === module exports block ===
 
 exports.THtmlStubItemsSet = THtmlStubItemsSet;
-exports.THtmlItemsListContainer = THtmlItemsListContainer;
-exports.THtmlItemsListController = THtmlItemsListController;

package/lib/lists-btn.js

@@ -1,4 +1,4 @@
-// [v0.1.060-20260110]
+// [v0.1.061-20260309]
 
 // === module init block ===
 
@@ -32,20 +32,8 @@ const {
 
 // === module main block ===
 
-/***
- * (* constant definitions *)
- */
-
 const BTS_DEF_GROUP_NAME = 'all';
 
-/***
- * (* function definitions *)
- */
-
-/***
- * (* class definitions *)
- */
-
 /**
  * A description for list buttons set.
  * @typedef {Object} listButtonsSetDesc
@@ -206,9 +194,8 @@ class THtmlListButtonsController {
     pushEventHandler(this.#_events, name, evnt);
   }
 };
+exports.THtmlListButtonsController = THtmlListButtonsController;
 
 // === module exports block ===
 
-exports.THtmlListButtonsController = THtmlListButtonsController;
-
 exports.BTS_DEF_GROUP_NAME = BTS_DEF_GROUP_NAME;

package/lib/lists-stubs.js

@@ -1,4 +1,4 @@
-// [v0.1.052-20260110]
+// [v0.1.053-20260309]
 
 // === module init block ===
 
@@ -14,18 +14,6 @@ const {
 
 // === module main block ===
 
-/***
- * (* constant definitions *)
- */
-
-/***
- * (* function definitions *)
- */
-
-/***
- * (* class definitions *)
- */
-
 /**
  * A settings to load a stub-elements.
  * @typedef {Object} OPT_ldstubs
@@ -292,7 +280,4 @@ class THtmlStubItemsSet {
   }
 
 };
-
-// === module exports block ===
-
 exports.THtmlStubItemsSet = THtmlStubItemsSet;

package/lib/mod-hfunc.js

@@ -1,28 +1,11 @@
-// [v0.1.065-20260110]
+// [v0.1.067-20260417]
 
 // === module init block ===
 
-const {
-  eventHelper, // [!] not oficialy exported yet
-} = require('@cntwg/html-helper');
-
 // === module inner block ===
 
-const {
-  pushEventHandler, removeEventHandler,
-  triggerEventHandler,
-} = eventHelper;
-
 // === module main block ===
 
-/***
- * (* constant definitions *)
- */
-
-/***
- * (* function definitions *)
- */
-
 /**
  * @function readOnClickEventInfo
  * @param {Event} e
@@ -51,16 +34,4 @@ function readOnClickEventInfo(e) {
   };
   return { item, onClickNum };
 };
-
-/***
- * (* class definitions *)
- */
-
-// === module exports block ===
-
 module.exports.readOnClickEventInfo = readOnClickEventInfo;
-
-// * re-exported *
-module.exports.pushEventHandler = pushEventHandler;
-module.exports.removeEventHandler = removeEventHandler;
-module.exports.triggerEventHandler = triggerEventHandler;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cntwg/html-ctrls-lists",
-  "version": "0.0.29",
+  "version": "0.0.31",
   "description": "An HTML-form component: lists",
   "author": "ygracs <cs70th-om@rambler.ru>",
   "license": "MIT",
@@ -33,14 +33,15 @@
     "#test-dir/*": "./__test__/*"
   },
   "dependencies": {
-    "@cntwg/html-ctrls-buttons": "^0.0.29",
-    "@cntwg/html-helper": "^0.1.1",
-    "@ygracs/bsfoc-lib-js": "^0.3.3",
-    "@ygracs/lists-lib-js": "^0.1.1"
+    "@cntwg/html-ctrls-buttons": "~0.1.0",
+    "@cntwg/html-helper": "~0.1.3",
+    "@ygracs/bsfoc-lib-js": "~0.3.4",
+    "@ygracs/lists-lib-js": "~0.2.0"
   },
   "devDependencies": {
-    "jest": "^30.2.0",
-    "jest-environment-jsdom": "^30.2.0",
+    "@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"
   }