@cntwg/html-helper 0.0.21 → 0.0.23

package/doc/html-ctrls-list.md

@@ -1,13 +1,14 @@
->|***rev.*:**|0.1.18|
+>|***rev.*:**|0.1.22|
 >|:---|---:|
->|date:|2023-11-19|
+>|date:|2024-11-13|
 
 ## Introduction
 
-This paper describes a classes provided by `html-ctrls-list.js` module.
+This paper describes a classes provided by `list.js`, `lists-stubs.js` and `lists-btn.js` of `html-ctrls` sub-module.
 
 ## Module classes
 
+<a name="THtmlItemsListContainer"></a>
 ### **THtmlItemsListContainer**
 
 This class provide a base container useful when dealing with a list elements placed on an HTML-form.
@@ -20,139 +21,273 @@ The class constructor creates a new instance of the class.
 
 The class constructor receives a parameters listed below:
 
-|parameter name|value type|default value|description|
+| parameter name | value type | default value | description |
 |:---|---|---:|:---|
-|`host`|`HTMLElement`|`undefined`|points to a host element which holds a list items|
-|`options`|`object`|---|contains a container settings|
+| `host` | `HTMLElement` | `undefined` | points to a host element which holds a list items |
+| `options` | `object` | --- | contains a container settings |
 
 ##### `options` parameter
 
 The `options` structure has listed below:
 
-|option name|value type|default value|description|
+| option name | value type | default value | description |
 |:---|---|---:|:---|
-|`autoHideNewItems`|`boolean`|`false`|alters behavior of the `addItem` class method. If set to `true`, the item which was added to a container members will be automatically hidden|
-|`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`|`array`|---|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|
+| `autoHideNewItems` | `boolean` | `false` |alters behavior of the `addItem` class method. If set to `true`, the item which was added to a container members will be automatically hidden |
+| `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
 
-The table below describes a properties of a `THtmlItemsListContainer` class:
+<a name="THtmlItemsListContainer+count"></a>
+##### **count**
 
-|property name|property type|read only|description|
-|:---|---|---|:---|
-|`count`|`number`|yes|contains a quantity of the items which holds by a container|
-|`curIndex`|`index`|yes|presents an index of a current item|
-|`minIndex`|`index`|yes|represents a minimum possible index for an item inside the container|
-|`maxIndex`|`index`|yes|represents a maximum possible index for an item inside the container|
-|`prevIndex`|`index`|yes|presents an index of the previous item before the current|
-|`nextIndex`|`index`|yes|presents an index of the next item after the current|
-|`curItem`|`HTMLElement` or `null`|yes|represents an item addressed by the `curIndex`|
+| property type | read only | description |
+|---|---|:---|
+| `number` | yes | contains a quantity of the elements the container holds |
+
+<a name="THtmlItemsListContainer+curIndex"></a>
+##### **curIndex**
+
+| property type | read only | description |
+|---|---|:---|
+| `number` | yes | represents an index of the current element |
+
+<a name="THtmlItemsListContainer+minIndex"></a>
+##### **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**
+
+| property type | read only | description |
+|---|---|:---|
+| `number` | yes | represents a maximum possible index for an element inside the container |
+
+<a name="THtmlItemsListContainer+prevIndex"></a>
+##### **prevIndex**
+
+| property type | read only | description |
+|---|---|:---|
+| `number` | yes | represents an index of the previous element before the current |
+
+<a name="THtmlItemsListContainer+nextIndex"></a>
+##### **nextIndex**
+
+| property type | read only | description |
+|---|---|:---|
+| `number` | yes | represents an index of the next element after the current |
+
+<a name="THtmlItemsListContainer+curItem"></a>
+##### **curItem**
+
+| property type | read only | description |
+|---|---|:---|
+| `?HTMLElement` | yes | represents an element addressed by the `curIndex` |
 
 #### class methods
 
-##### **clear()**
+<a name="THtmlItemsListContainer+clear"></a>
+##### **clear()** => `void`
 
 This method deletes all items that holds by the container.
 
-##### **isEmpty()**
+<a name="THtmlItemsListContainer+isEmpty"></a>
+##### **isEmpty()** => `boolean`
 
 This method returns `true` if the container has no items.
 
-##### **isNotEmpty()**
+<a name="THtmlItemsListContainer+isNotEmpty"></a>
+##### **isNotEmpty()** => `boolean`
 
 This method returns `true` if the container has at least one item.
 
-##### **chkIndex(value)**
+<a name="THtmlItemsListContainer+chkIndex"></a>
+##### **chkIndex(value)** => `boolean`
 
 This method returns `true` if a given `value` represents a valid index within the range of the list.
 
-##### **chkIndexEx(value\[, mode])**
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `value` | `any` | --- | a value to be verified |
+
+<a name="THtmlItemsListContainer+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.
 
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `value` | `any` | --- | a value to be verified |
+| `mode` | `boolean` | `false` | a flag to switch result value type |
+
 The `mode` parameter treats as follows:
 
 - if set to `false`, the result returned by the method is a `boolean` value;
-- if `mode` parameter set to `true`, the result returned by the method has an index type;
-- if not given or has a type of not a `boolean` value, the default value is used which is set to `false`.
+- 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.
 
-##### **srchIndex(item)**
+<a name="THtmlItemsListContainer+srchIndex"></a>
+##### **srchIndex(item)** => `number`
 
 This method tries to find a given item in the list and if it is found returns its index.
 
-##### **srchIndexByAttr(name, value)**
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `item` | `?HTMLElement` | --- | an element to search |
+
+<a name="THtmlItemsListContainer+srchIndexByAttr"></a>
+##### **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.
 
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `name` | `string` | --- | an attribute name |
+| `value` | `any` | --- | an attribute value |
+
 The `value` can be a `boolean`, `number` or a `string`. If it is not given the empty string value is used. In any other cases the method will failed.
 
 > 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.
 
-##### **srchIndexByID(value)**
+<a name="THtmlItemsListContainer+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 (*see description of `srchIndexByAttr` method for details how a `value` parameter is used*).
 
-##### **setCurIndex(value)**
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `value` | `string` | --- | an ID value |
+
+<a name="THtmlItemsListContainer+setCurIndex"></a>
+##### **setCurIndex(index)** => `boolean`
 
 This method sets a current item index in the list. If succeed `true` is returned.
 
-##### **rstCurIndex()**
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `index` | `number`, `string` | --- | an element index |
 
-This method resets a current item index in the list.
+<a name="THtmlItemsListContainer+rstCurIndex"></a>
+##### **rstCurIndex()** => `void`
+
+This method resets a current element index in the list.
+
+<a name="THtmlItemsListContainer+getItem"></a>
+##### **getItem(index)** => `?HTMLElement`
 
-##### **getItem(index)**
+This method returns an element addressed by a given `index`.
 
-This method returns an item addressed by a given `index`.
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `index` | `number`, `string` | --- | an element index |
 
-##### **getItemByAttr(name, value)**
+<a name="THtmlItemsListContainer+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 (*see description of `srchIndexByAttr` method for details how a `value` parameter is used*).
 
-##### **getItemByID(value)**
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `name` | `string` | --- | an attribute name |
+| `value` | `any` | --- | an attribute value |
+
+<a name="THtmlItemsListContainer+getItemByID"></a>
+##### **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*).
 
-##### **addItem(item\[, options])**
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `value` | `string` | --- | an ID value |
+
+<a name="THtmlItemsListContainer+addItem"></a>
+##### **addItem(item\[, options])** => `number`
 
 This method adds a given item to a container members and if succeed returns its index.
 
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `item` | `HTMLElement` | --- | some element |
+| `options` | `boolean` | `false` | a flag to switch mode |
+
 If `options` parameter is given and is set to `true`, in case of success, the `curIndex` property is adjusted by the method.
 
 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.
 
-##### **delItem(index\[, options])**
+<a name="THtmlItemsListContainer+delItem"></a>
+##### **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.
 
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `index` | `number`, `string` | --- | an element index |
+| `options` | `boolean` | `true` | a flag to switch mode |
+| `optEx` | `boolean` | `true` | a flag to switch mode |
+
 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.
 
-##### **selectItem(index\[, options])**
+<a name="THtmlItemsListContainer+selectItem"></a>
+##### **selectItem(index\[, options])** => `boolean`
 
 This method selects an item addressed by an `index` and if succeed `true` is returned.
 
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `index` | `number`, `string` | --- | an element index |
+| `options` | `boolean` | `false` | a flag to switch mode |
+
 If `options` parameter is given and is set to `true`, in case of success, the `curIndex` property is adjusted by the method.
 
-##### **unselectItem(index)**
+<a name="THtmlItemsListContainer+unselectItem"></a>
+##### **unselectItem(index)** => `boolean`
 
 This method unselects an item addressed by an `index` and if succeed `true` is returned.
 
-##### **hideItem(index)**
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `index` | `number`, `string` | --- | an element index |
+
+<a name="THtmlItemsListContainer+hideItem"></a>
+##### **hideItem(index)** => `boolean`
 
 This method hides an item addressed by an `index` and if succeed `true` is returned.
 
-##### **showItem(index)**
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `index` | `number`, `string` | --- | an element index |
+
+<a name="THtmlItemsListContainer+showItem"></a>
+##### **showItem(index)** => `boolean`
 
 This method shows an item addressed by an `index` and if succeed `true` is returned.
 
-##### **isSelectedItem(index)**
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `index` | `number`, `string` | --- | an element index |
+
+<a name="THtmlItemsListContainer+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.
 
-##### **isHiddenItem(index)**
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `index` | `number`, `string` | --- | an element index |
+
+<a name="THtmlItemsListContainer+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.
 
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `index` | `number`, `string` | --- | an element index |
+
+<a name="THtmlItemsListController"></a>
 ### **THtmlItemsListController**
 
 This class implements a controller that provide mechanism for managing a list container and its elements placed on an HTML-form.
@@ -165,139 +300,296 @@ The class constructor creates a new instance of the class.
 
 The class constructor receives a parameters listed below:
 
-|parameter name|value type|default value|description|
+| parameter name | value type | default value | description |
 |:---|---|---:|:---|
-|`host`|`HTMLElement`|`undefined`|points to a host element which holds a list items|
-|`options`|`object`|---|contains a set of a settings for a container|
+| `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
 
 The `options` structure has listed below:
 
-|option name|value type|default value|description|
+| option name | value type | default value | description |
 |:---|---|---:|:---|
-|`autoHideNewItems`|`boolean`|`false`|for details see options on `THtmlItemsListContainer` class constructor section|
-|`markCurrentItem`|`boolean`|`false`|for details see options on `THtmlItemsListContainer` class constructor section|
-|`itemBaseClassID`|`array`|---|for details see options on `THtmlItemsListContainer` class constructor section|
-|`showStubsIfEmpty`|`boolean`|`false`|if set, in case of the empty list, the default stub-item will be displayed|
-|`allowGroupSelection`|`boolean`|`false`|if set the more than one element can be selected in the list|
-|`allowSelectionLocks`|`boolean`|`false`|\<*reserved, experimental*>|
+| `autoHideNewItems` | `boolean` | `false` | for details see options on `THtmlItemsListContainer` class constructor section |
+| `markCurrentItem` | `boolean` | `false` | for details see options on `THtmlItemsListContainer` class constructor section |
+| `itemBaseClassID` | `string`, `string[]` | --- | for details see options on `THtmlItemsListContainer` class constructor section |
+| `showStubsIfEmpty` | `boolean` | `false` | if set, in case of the empty list, the default stub-item will be displayed |
+| `allowGroupSelection` | `boolean` | `false` | if set the more than one element can be selected in the list |
+| `allowSelectionLocks` | `boolean` | `false` | \<*reserved, experimental*> |
 
 #### class properties
 
-|property name|property type|read only|description|
-|:---|---|---|:---|
-|`count`|`number`|yes|contains quantity of items which holds by container|
-|`curIndex`|`index`|yes|presents an index of a current item|
-|`maxIndex`|`index`|yes|represents a max possible index for an item inside the container|
-|`prevIndex`|`index`|yes|presents an index of a previous item before the current|
-|`nextIndex`|`index`|yes|presents an index of a next item after the current|
-|`curItem`|`HTMLElement` or `null`|yes|represents an item addressed by `curIndex`|
-|`SelectedItems`|`array`|yes|returns an array of a selected items|
-|`StubItems`|`THtmlStubItemsSet`|yes|returns a `THtmlStubItemsSet` instance|
-|`isSelectionLocked`|`boolean`|yes|returns `true` if selections of an items is not allowed|
+<a name="THtmlItemsListController+count"></a>
+##### **count**
+
+| property type | read only | description |
+|---|---|:---|
+| `number` | yes | contains a quantity of the elements the container holds |
+
+<a name="THtmlItemsListController+curIndex"></a>
+##### **curIndex**
+
+| property type | read only | description |
+|---|---|:---|
+| `number` | yes | represents an index of the current element |
+
+<a name="THtmlItemsListController+minIndex"></a>
+##### **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**
+
+| property type | read only | description |
+|---|---|:---|
+| `number` | yes | represents a maximum possible index for an element inside the container |
+
+<a name="THtmlItemsListController+prevIndex"></a>
+##### **prevIndex**
+
+| property type | read only | description |
+|---|---|:---|
+| `number` | yes | represents an index of the previous element before the current |
+
+<a name="THtmlItemsListController+nextIndex"></a>
+##### **nextIndex**
+
+| property type | read only | description |
+|---|---|:---|
+| `number` | yes | represents an index of the next element after the current |
+
+<a name="THtmlItemsListController+curItem"></a>
+##### **curItem**
+
+| property type | read only | description |
+|---|---|:---|
+| `?HTMLElement` | yes | represents an element addressed by the `curIndex` |
+
+<a name="THtmlItemsListController+isSelectionLocked"></a>
+##### **isSelectionLocked**
+
+| property type | read only | description |
+|---|---|:---|
+| `boolean` | yes | returns `true` if selections of an items is not allowed |
+
+<a name="THtmlItemsListController+SelectedItems"></a>
+##### **SelectedItems**
+
+| property type | read only | description |
+|---|---|:---|
+| `HTMLElement[]` | yes | returns an array of the selected elements |
+
+<a name="THtmlItemsListController+StubItems"></a>
+##### **StubItems**
+
+| property type | read only | description |
+|---|---|:---|
+| `THtmlStubItemsSet` | yes | returns a `THtmlStubItemsSet` instance |
 
 #### class methods
 
-##### **clear()**
+<a name="THtmlItemsListController+clear"></a>
+##### **clear()** => `void`
 
 This method deletes all items that is hold by the list.
 
-##### **lockItemsSelection()**
+<a name="THtmlItemsListController+lockItemsSelection"></a>
+##### **lockItemsSelection()** => `void`
 
 This method blocks a selection of the items in the list.
 
-##### **unlockItemsSelection()**
+<a name="THtmlItemsListController+unlockItemsSelection"></a>
+##### **unlockItemsSelection()** => `void`
 
 This method allows a selection of the items in the list.
 
-##### **isEmpty()**
+<a name="THtmlItemsListContainer+isEmpty"></a>
+##### **isEmpty()** => `boolean`
 
 This method returns `true` if the list has no items.
 
-##### **isNotEmpty()**
+<a name="THtmlItemsListContainer+isNotEmpty"></a>
+##### **isNotEmpty()** => `boolean`
 
 This method returns `true` if the list has at least one item.
 
-##### **chkIndex(value)**
+<a name="THtmlItemsListContainer+chkIndex"></a>
+##### **chkIndex(value)** => `boolean`
 
 This method returns `true` if a given value represent a valid index within the range of the list.
 
-##### **chkIndexEx(value\[, mode])**
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `value` | `any` | --- | a value to be verified |
+
+<a name="THtmlItemsListContainer+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.
 
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `value` | `any` | --- | a value to be verified |
+| `mode` | `boolean` | `false` | a flag to switch result value type |
+
 If `mode` parameter set to `false` (*its default value*), the result returned by the method is a `boolean` value.
 
 If `mode` parameter set to `true`, the result returned by the method has an index type.
 
-##### **srchIndex(item)**
+<a name="THtmlItemsListContainer+srchIndex"></a>
+##### **srchIndex(item)** => `number`
 
 This method tries to find a given item in the list and if it is found returns its index.
 
-##### **srchIndexByAttr(name, value)**
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `item` | `?HTMLElement` | --- | an element to search |
+
+<a name="THtmlItemsListContainer+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.
 
-##### **srchIndexByID(value)**
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `name` | `string` | --- | an attribute name |
+| `value` | `any` | --- | an attribute value |
+
+<a name="THtmlItemsListContainer+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.
 
-##### **setCurIndex(value)**
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `value` | `string` | --- | an ID value |
+
+<a name="THtmlItemsListController+setCurIndex"></a>
+##### **setCurIndex(index)** => `boolean`
 
 This method sets a current item index in the list. If succeed `true` is returned.
 
-##### **rstCurIndex()**
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `index` | `number`, `string` | --- | an element index |
+
+<a name="THtmlItemsListController+rstCurIndex"></a>
+##### **rstCurIndex()** => `void`
 
 This method resets a current item index in the list.
 
-##### **getItem(index)**
+<a name="THtmlItemsListContainer+getItem"></a>
+##### **getItem(index)** => `?HTMLElement`
 
 This method returns an item addressed by a given index.
 
-##### **getItemByAttr(name, value)**
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `index` | `number`, `string` | --- | an element index |
+
+<a name="THtmlItemsListContainer+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.
 
-##### **getItemByID(value)**
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `name` | `string` | --- | an attribute name |
+| `value` | `any` | --- | an attribute value |
+
+<a name="THtmlItemsListContainer+getItemByID"></a>
+##### **getItemByID(value)** => `?HTMLElement`
 
 This method tries to find an item by its `ID`-attribute in the list and if found returns it.
 
-##### **addItem(item\[, options])**
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `value` | `string` | --- | an ID value |
+
+<a name="THtmlItemsListController+addItem"></a>
+##### **addItem(item\[, options])** => `number`
 
 This method adds a given item to a list members and if succeed returns its index.
 
-##### **delItem(index\[, options])**
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `item` | `HTMLElement` | --- | some element |
+| `options` | `boolean` | `false` | a flag to switch mode |
+
+<a name="THtmlItemsListController+delItem"></a>
+##### **delItem(index\[, options])** => `boolean`
 
 This method deletes an item addressed by `index` from a list members and if succeed `true` is returned.
 
-##### **selectItem(index\[, options])**
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `index` | `number`, `string` | --- | an element index |
+| `options` | `boolean` | `true` | a flag to switch mode |
+
+<a name="THtmlItemsListController+selectItem"></a>
+##### **selectItem(index\[, options])** => `boolean`
 
 This method selects an item addressed by an `index` and if succeed `true` is returned.
 
-##### **unselectItem(index)**
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `index` | `number`, `string` | --- | an element index |
+| `options` | `boolean` | `false` | a flag to switch mode |
+
+<a name="THtmlItemsListController+unselectItem"></a>
+##### **unselectItem(index)** => `boolean`
 
 This method unselects an item addressed by an `index` and if succeed `true` is returned.
 
-##### **hideItem(index)**
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `index` | `number`, `string` | --- | an element index |
+
+<a name="THtmlItemsListController+hideItem"></a>
+##### **hideItem(index)** => `boolean`
 
 This method hides an item addressed by an `index` and if succeed `true` is returned.
 
-##### **showItem(index)**
+<a name="THtmlItemsListController+showItem"></a>
+##### **showItem(index)** => `boolean`
 
 This method shows an item addressed by an `index` and if succeed `true` is returned.
 
-##### **isSelectedItem(index)**
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `index` | `number`, `string` | --- | an element index |
+
+<a name="THtmlItemsListContainer+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.
 
-##### **isHiddenItem(index)**
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `index` | `number`, `string` | --- | an element index |
+
+<a name="THtmlItemsListContainer+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.
 
-##### **on(name, event)**
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `index` | `number`, `string` | --- | an element index |
+
+<a name="THtmlItemsListController+on"></a>
+##### **on(name, event)** => `void`
 
-This method sets event handler for the list event addressed by `name` parameter.
+This method sets event handler for the list event addressed by a `name` parameter.
+
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `name` | `string` | --- | an event name |
+| `event` | `function` | --- | a callback function |
 
 > 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.
 
@@ -305,18 +597,19 @@ This method sets event handler for the list event addressed by `name` parameter.
 
 The class generates the events listed in the table bellow:
 
-|event name|description|
+| event name | description |
 |:---|:---|
-|`list-clear`|fired if the list is cleared or a last item was removed|
-|`first-item-added`|fired when a first item was added to the list. This event will occur before `item-added` event was triggered|
-|`item-added`|fired when an item was added to the list|
-|`item-removed`|fired when an item was deleted from the list. It will not occur in case the item is the last.|
-|`current-item-chosen`|fired when an item was choosen as current|
-|`item-selected`|fired when an item was marked as selected in the list|
-|`item-unselected`|fired when an item was unmarked as selected in the list|
-|`item-hidden`|fired when an item was marked as hidden in the list|
-|`item-shown`|fired when an item was marked as non-hidden in the list|
-
+| `list-clear` | fired if the list is cleared or a last item was removed |
+| `first-item-added` | fired when a first item was added to the list. This event will occur before `item-added` event was triggered |
+| `item-added` | fired when an item was added to the list |
+| `item-removed` | fired when an item was deleted from the list. It will not occur in case the item is the last. |
+| `current-item-chosen` | fired when an item was chosen as current |
+| `item-selected` | fired when an item was marked as selected in the list |
+| `item-unselected` | fired when an item was unmarked as selected in the list |
+| `item-hidden` | fired when an item was marked as hidden in the list |
+| `item-shown` | fired when an item was marked as non-hidden in the list |
+
+<a name="THtmlStubItemsSet"></a>
 ### **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.
@@ -329,96 +622,155 @@ The class constructor creates a new instance of the class.
 
 The class constructor receives a parameters listed below:
 
-|parameter name|value type|default value|description|
+| parameter name | value type | default value | description |
 |:---|---|---:|:---|
-|`host`|`HTMLElement`|---|points to a host element which holds a list items|
-|`options`|`object` or `array`|`undefined`|contains an object that is send to a class `loadItems` method|
+| `host` | `HTMLElement` | --- | points to a host element which holds a list items |
+| `options` | `object`, `array` | `undefined` | contains an object that is send to a class `loadItems` method |
 
 ##### `options` parameter
 
 The `options` structure has listed below:
 
-|option name|value type|default value|description|
+| option name | value type | default value | description |
 |:---|---|---:|:---|
-|`items`|`array`|`undefined`|defines a list of the items to load|
-|`defaultItem`|`string`|EMPTY_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|
+| `items` | `array` | `undefined` | defines a list of the entries to load. Each entry contains a `name`-`element` pair. |
+| `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 (*`since: v0.0.23` - deprecated*) |
+
+> NOTE: For more details on an `items` element see an description of a [`loadItems`](#THtmlStubItemsSet+loadItems) class method.
 
 #### class properties
 
-|property name|property type|read only|description|
-|:---|---|---|:---|
-|`count`|`number`|yes|presents quantity of items which holds by the set|
-|`defItem`|'string`|no|defines an item name which is used by default|
+<a name="THtmlStubItemsSet+count"></a>
+##### **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**
+
+| property type | read only | description |
+|---|---|:---|
+| `string` | no | defines an element name which is used by default |
 
 #### class methods
 
-##### **clear()**
+<a name="THtmlStubItemsSet+clear"></a>
+##### **clear()** => `void`
 
 This class method deletes all items hold by the set.
 
-##### **hasItem(name)**
+<a name="THtmlStubItemsSet+hasItem"></a>
+##### **hasItem(name)** => `boolean`
 
 This class method returns `true` if an item named by `name` exists in the set and `false` if else.
 
-##### **hasItems()**
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `name` | `string` | --- | an element name |
+
+<a name="THtmlStubItemsSet+hasItems"></a>
+##### **hasItems()** => `boolean`
 
 This class method returns `true` if the set hold any items and `false` if not.
 
-##### **getItem(name)**
+<a name="THtmlStubItemsSet+getItem"></a>
+##### **getItem(name)** => `?HTMLElement`
 
 This class method returns an item named by `name` if it exists in the set and `null` if else.
 
-##### **addItem(name, item\[, actForce])**
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `name` | `string` | --- | an element name |
+
+<a name="THtmlStubItemsSet+addItem"></a>
+##### **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`.
 
-The `actForce` parameter if given alters the method behaviour:
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `name` | `string` | --- | an element name |
+| `item` | `HTMLElement` | --- | an element |
+| `options` | `boolean` | `false` | flag that defines whether to run in `force`-mode |
+
+The `actForce` parameter if given alters the method behavior:
 
 - If set to `true` it force replacements of an existing item which label is equal to `name`;
 - If set to `false` and item with the same label already exists the method will failed;
 - If parameter is not given or not of a `boolean` type its default value meant to be `false`.
 
-##### **delItem(name)**
+<a name="THtmlStubItemsSet+delItem"></a>
+##### **delItem(name)** => `boolean`
 
 This class method tries to delete item named by `name` from the set and if succeed `true` is returned.
 
-##### **showItem(name)**
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `name` | `string` | --- | an element name |
+
+<a name="THtmlStubItemsSet+showItem"></a>
+##### **showItem(name)** => `boolean`
 
 This class method tries to make item named by `name` visible on HTML-form and if succeed `true` is returned.
 
-##### **hideItem(name)**
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `name` | `string` | --- | an element name |
+
+<a name="THtmlStubItemsSet+hideItem"></a>
+##### **hideItem(name)** => `boolean`
 
 This class method tries to make item named by `name` invisible on HTML-form and if succeed `true` is returned.
 
-##### **setDefItem(name)**
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `name` | `string` | --- | an element name |
+
+<a name="THtmlStubItemsSet+setDefItem"></a>
+##### **setDefItem(name)** => `boolean`
 
 This class method tries to set item named by `name` as a default item and if succeed `true` is returned.
 
-##### **rstDefItem()**
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `name` | `string` | --- | an element name |
+
+<a name="THtmlStubItemsSet+rstDefItem"></a>
+##### **rstDefItem()** => `void`
 
 This class method resets a default item.
 
-##### **showDefItem()**
+<a name="THtmlStubItemsSet+showDefItem"></a>
+##### **showDefItem()** => `boolean`
 
 This class method is similar to `showItem` method but is performed on a default item.
 
-##### **hideDefItem()**
+<a name="THtmlStubItemsSet+hideDefItem"></a>
+##### **hideDefItem()** => `boolean`
 
 This class method is similar to `hideItem` method but is performed on a default item.
 
-##### **loadItems(list\[, options])**
+<a name="THtmlStubItemsSet+loadItems"></a>
+##### **loadItems(list\[, 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.
 
-The `list` parameter is an `object` that contains the following set of values:
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `list` | `array`, `object` | --- | an array of entries or a special descriptive object |
+| `options` | `boolean`, `object` | --- | an options |
+
+If the `list` parameter is an `object` that contains the following set of values:
 
-|value name|value type|default value|description|
+| option name | value type | default value | description |
 |:---|---|---:|:---|
-|`defaultItem`|`string`|EMPTY_STRING|if set it defines a name of the item used by default|
-|`items`|`array`|`undefined`|defines a list of the items to load|
+| `items` | `array` | `undefined` | defines a list of the entries to load. Each entry contains a `name`-`element` pair. |
+| `defaultItem` | `string` | --- | if set it defines a name of the item used by default |
 
-If the `list` parameter is an `array` it used as value of an `list.items` options and if such a case the `list.defultItem` will be set to defaults.
+If the `list` parameter is an `array` it used as value of a `list.items` options and in such a case the name for a default element receives from an `options.defaultItem` if given.
 
 Note that each element of a `list.items` can be:
 
@@ -430,11 +782,93 @@ Note that each element of a `list.items` can be:
 
   '{ **name**: \<*`item name`*>, **item**: \<*`object`*>}'
 
-The `options` parameter is an `object` that contains the following set of parameters:
+If the `options` parameter is an `object` that contains the following set of parameters:
 
-|option name|value type|default value|description|
+| option name | value type | default value | description |
 |:---|---|---:|:---|
-|`useClear`|`boolean`|`true`|if set to `true`, before the load of the items, the list is cleared|
-|`force`|`boolean`|`false`|if set to `true`, the item which is already present will be replaced with a new one|
+| `defaultItem` | `string` | --- | if set it defines a name of the item used by default |
+| `useClear` | `boolean` | `true` | if set to `true`, before the load of the items, the list is cleared |
+| `force` | `boolean` | `false` | if set to `true`, the item which is already present will be replaced with a new one |
 
 If the `options` parameter is a `boolean` value it treats as a `options.useClear` option.
+
+<a name="THtmlListButtonsController"></a>
+### **THtmlListButtonsController**
+
+This class provides a buttons controller to use with a list components to performs actions for list elements selection.
+
+#### class constructor
+
+The class constructor creates a new instance of the class.
+
+##### constructor parameters
+
+The class constructor receives an `options` parameter which structure has listed below:
+
+| option name | option type | default value | description |
+|:---|---|---:|:---|
+| `btnFirst` | `?HTMLElement` | `undefined` | defines an HTML-button which will select the first element |
+| `btnPrev` | `?HTMLElement` | `undefined` | defines an HTML-button which will select the previous element |
+| `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
+
+This class has none.
+
+#### class methods
+
+<a name="THtmlListButtonsController+disableAll"></a>
+##### **disableAll()** => `void`
+
+This method disables all buttons that holds by the controller.
+
+<a name="THtmlListButtonsController+disableBkwd"></a>
+##### **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`
+
+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`
+
+This method enables all buttons that holds by the controller.
+
+<a name="THtmlListButtonsController+enableBkwd"></a>
+##### **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`
+
+This method enables all buttons in *'move forward'* group (*i.e. `btnNext` and `btnLast`*) that holds by the controller.
+
+#### class methods (*special*)
+
+<a name="THtmlListButtonsController+on"></a>
+##### **on(name, event)** => `void`
+
+This method sets event handler addressed by a `name` parameter.
+
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `name` | `string` | --- | an event name |
+| `event` | `function` | --- | a callback function |
+
+> 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
+
+The class generates the events listed in the table bellow:
+
+| event name | description |
+|:---|:---|
+| `btn-first-pressed` | fired if the `btnFirst` was pressed |
+| `btn-prev-pressed` | fired if the `btnPrev` was pressed |
+| `btn-next-pressed` | fired if the `btnNext` was pressed |
+| `btn-last-pressed` | fired if the `btnLast` was pressed |