@cntwg/html-helper 0.0.14

package/doc/html-ctrls-list.md

@@ -0,0 +1,405 @@
+>|***rev.*:**|0.1.9|
+>|:---|---:|
+>|date:|2022-09-12|
+
+## Introduction
+
+This paper describes a classes provided by `html-ctrls-list.js` module.
+
+## Module classes
+
+### **THtmlItemsListContainer**
+
+This class provide a base container useful when dealing with a list elements placed on an HTML-form.
+
+#### class constructor
+
+The class constructor creates a new instance of the class. It receives a parameters listed below:
+
+|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|
+
+The `options` structure has listed below:
+
+|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|
+
+#### class properties
+
+The table below describes a properties of a `THtmlItemsListContainer` class:
+
+|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`|
+
+#### class methods
+
+##### **clear()**
+
+This method deletes all items that holds by the container.
+
+##### **isEmpty()**
+
+This method returns `true` if the container has no items.
+
+##### **isNotEmpty()**
+
+This method returns `true` if the container has at least one item.
+
+##### **chkIndex(value)**
+
+This method returns `true` if a given `value` represents a valid index within the range of the list.
+
+##### **chkIndexEx(value\[, mode])**
+
+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.
+
+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`.
+
+##### **srchIndex(item)**
+
+This method tries to find a given item in the list and if it is found returns its index.
+
+##### **srchIndexByAttr(name, value)**
+
+This method tries to find an item by its given attribute in the list and if it is found returns its index.
+
+##### **srchIndexByID(value)**
+
+This method tries to find an item by its `ID`-attribute in the list and if it is found returns its index.
+
+##### **setCurIndex(value)**
+
+This method sets a current item index in the list. If succeed `true` is returned.
+
+##### **rstCurIndex()**
+
+This method resets a current item index in the list.
+
+##### **getItem(index)**
+
+This method returns an item addressed by a given `index`.
+
+##### **getItemByAttr(name, value)**
+
+This method tries to find an item by its given attribute in the list and if found returns it.
+
+##### **getItemByID(value)**
+
+This method tries to find an item by its `ID`-attribute in the list and if found returns it.
+
+##### **addItem(item\[, options])**
+
+This method adds a given item to a container members and if succeed returns its index.
+
+If `options` parameter is given and is set to `true`, in case of success, the `curIndex` property is adjusted by the method.
+
+##### **delItem(index\[, options])**
+
+This method deletes an item addressed by the given `index` from a container members and if succeed `true` is returned.
+
+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])**
+
+This method selects an item addressed by an `index` and if succeed `true` is returned.
+
+If `options` parameter is given and is set to `true`, in case of success, the `curIndex` property is adjusted by the method.
+
+##### **unselectItem(index)**
+
+This method unselects an item addressed by an `index` and if succeed `true` is returned.
+
+##### **hideItem(index)**
+
+This method hides an item addressed by an `index` and if succeed `true` is returned.
+
+##### **showItem(index)**
+
+This method shows an item addressed by an `index` and if succeed `true` is returned.
+
+##### **isSelectedItem(index)**
+
+This method checks whether or not an item addressed by an `index` is selected and if so `true` is returned.
+
+##### **isHiddenItem(index)**
+
+This method checks whether or not an item addressed by an `index` is hidden and if so `true` is returned.
+
+### **THtmlItemsListController**
+
+This class implements a controller that provide mechanism for menaging a list container and its elements placed on an HTML-form.
+
+#### class constructor
+
+The class constructor creates a new instance of the class. It receives a parameters listed below:
+
+|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|
+
+The `options` structure has listed below:
+
+|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|
+|`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|
+
+#### class methods
+
+##### **clear()**
+
+This method deletes all items that is hold by the list.
+
+##### **lockItemsSelection()**
+
+This method blocks a selection of the items in the list.
+
+##### **unlockItemsSelection()**
+
+This method allows a selection of the items in the list.
+
+##### **isEmpty()**
+
+This method returns `true` if the list has no items.
+
+##### **isNotEmpty()**
+
+This method returns `true` if the list has at least one item.
+
+##### **chkIndex(value)**
+
+This method returns `true` if a given value represent a valid index within the range of the list.
+
+##### **chkIndexEx(value\[, mode])**
+
+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.
+
+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)**
+
+This method tries to find a given item in the list and if it is found returns its index.
+
+##### **srchIndexByAttr(name, value)**
+
+This method tries to find an item by its given attribute in the list and if it is found returns its index.
+
+##### **srchIndexByID(value)**
+
+This method tries to find an item by its `ID`-attribute in the list and if it is found returns its index.
+
+##### **setCurIndex(value)**
+
+This method sets a current item index in the list. If succeed `true` is returned.
+
+##### **rstCurIndex()**
+
+This method resets a current item index in the list.
+
+##### **getItem(index)**
+
+This method returns an item addressed by a given index.
+
+##### **getItemByAttr(name, value)**
+
+This method tries to find an item by its given attribute in the list and if found returns it.
+
+##### **getItemByID(value)**
+
+This method tries to find an item by its `ID`-attribute in the list and if found returns it.
+
+##### **addItem(item\[, options])**
+
+This method adds a given item to a list members and if succeed returns its index.
+
+##### **delItem(index\[, options])**
+
+This method deletes an item addressed by `index` from a list members and if succeed `true` is returned.
+
+##### **selectItem(index\[, options])**
+
+This method selects an item addressed by an `index` and if succeed `true` is returned.
+
+##### **unselectItem(index)**
+
+This method unselects an item addressed by an `index` and if succeed `true` is returned.
+
+##### **hideItem(index)**
+
+This method hides an item addressed by an `index` and if succeed `true` is returned.
+
+##### **showItem(index)**
+
+This method shows an item addressed by an `index` and if succeed `true` is returned.
+
+##### **isSelectedItem(index)**
+
+This method checks whether or not an item addressed by an `index` is selected and if so `true` is returned.
+
+##### **isHiddenItem(index)**
+
+This method checks whether or not an item addressed by an `index` is hidden and if so `true` is returned.
+
+##### **on(name, event)**
+
+This method sets event handler for the list event addressed by `name` parameter.
+
+> Note: for current implementation you can't reset or set new event handler (especailly another one) if a hanlder with the same name exists already.
+
+#### class events
+
+The class generates the events listed in the table bellow:
+
+|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 selested in the list|
+|`item-unselected`|fired when an item was marked as unselested 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|
+
+### **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
+
+The class constructor creates a new instance of the class. It receives a parameters listed below:
+
+|parameter name|value type|default value|description|
+|:---|---|---:|:---|
+|`host`|`HTMLElement`|---|points to a host element which holds a list items|
+|`items`|`object` or `array`|`undefined`|contains an object that is send to a class `loadItems` 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|
+
+#### class methods
+
+##### **clear()**
+
+This class method deletes all items hold by the set.
+
+##### **hasItem(name)**
+
+This class method returns `true` if an item named by `name` exists in the set and `false` if else.
+
+##### **hasItems()**
+
+This class method returns `true` if the set hold any items and `false` if not.
+
+##### **getItem(name)**
+
+This class method returns an item named by `name` if it exists in the set and `null` if else.
+
+##### **addItem(name, item\[, actForce])**
+
+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:
+
+- If set to `true` it force replacements of an existing item which label is qual 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)**
+
+This class method tries to delete item named by `name` from the set and if succeed `true` is returned.
+
+##### **showItem(name)**
+
+This class method tries to make item named by `name` visible on HTML-form and if succeed `true` is returned.
+
+##### **hideItem(name)**
+
+This class method tries to make item named by `name` invisible on HTML-form and if succeed `true` is returned.
+
+##### **setDefItem(name)**
+
+This class method tries to set item named by `name` as a default item and if succeed `true` is returned.
+
+##### **rstDefItem()**
+
+This class method resets a default item.
+
+##### **showDefItem()**
+
+This class method is similar to `showItem` method but is performed on a default item.
+
+##### **hideDefItem()**
+
+This class method is similar to `hideItem` method but is performed on a default item.
+
+##### **loadItems(list\[, options])**
+
+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:
+
+|value 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|
+
+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.
+
+Note that each element of a `list.items` can be:
+
+- an `array` which contains a `key-value` pair
+
+  '[ \<*`item name`*>, \<*`object`*> ]'
+
+- an `object`:
+
+  '{ **name**: \<*`item name`*>, **item**: \<*`object`*>}'
+
+The `options` parameter is an `object` that contains the following set of parameters:
+
+|option name|value type|default value|description|
+|:---|---|---:|:---|
+|`useClear`|`boolean`|`true`|if set to `true`, before the load of the items, the list is cleared|
+|`load_as_new`|`boolean`|`true`|*will deprecate (use `useClear` instead)*|
+|`force`|`boolean`|`false`|if set to `true`, the item which is allready present will be replaced with a new one|
+
+If the `options` parameter is a `boolean` value it treats as a `options.useClear` option.

package/doc/html-helper-lib.md

@@ -0,0 +1,118 @@
+>|***rev.*:**|0.1.3|
+>|:---|---:|
+>|date:|2022-09-03|
+
+## Introduction
+
+This paper describes a base helpers provided by `html-helper-lib.js` module.
+
+##  Module constants
+
+### Set of constants 'CSS_CLASS_STRING'
+
+This set of constants provides some definitions of a base CSS-class strings which can be used as a class values of the HTML-element. Those are:
+
+|name|value|
+|:---|---:|
+|`CSS_CLASS_CURRENT`|'current'|
+|`CSS_CLASS_SELECTED`|'selected'|
+|`CSS_CLASS_ACTIVE`|'active'|
+|`CSS_CLASS_DISABLED`|'disabled'|
+|`CSS_CLASS_HIDDEN`|'hidden'|
+
+## Module functions
+
+### Logical functions
+
+#### **isHTMLElement(object)**
+
+This function checks whether or not a given object represents an HTML-element and if so returns `true` or `false` if else.
+
+#### **isSelectedHTMLElement(object)**
+
+This function checks if the given object represents an HTML-element and whether or not its class include an attribute which is equal to `CSS_CLASS_SELECTED`.
+
+#### **isCurrentHTMLElement(object)**
+
+This function checks if the given object represents an HTML-element and whether or not its class include an attribute which is equal to `CSS_CLASS_CURRENT`.
+
+#### **isActiveHTMLElement(object)**
+
+This function checks if the given object represents an HTML-element and whether or not its class include an attribute which is equal to `CSS_CLASS_ACTIVE`.
+
+#### **isHiddenHTMLElement(object)**
+
+This function checks if the given object represents an HTML-element and whether or not its class include an attribute which is equal to `CSS_CLASS_HIDDEN`.
+
+### Functions for element manipulations
+
+#### **hideHTMLElement(object)**
+
+This function hides HTML-element given by `object` parameter and if succeed `true` is returned.
+
+> Note: Technicly, the function provide a wrapper that applies the class attribute defined by 'CSS_CLASS_HIDDEN' for a given HTML-element.
+
+#### **showHTMLElement(object)**
+
+This function unhides HTML-element given by `object` parameter and if succeed `true` is returned.
+
+> Note: Technicly, the function provide a wrapper that removes the class attribute defined by 'CSS_CLASS_HIDDEN' for a given HTML-element.
+
+#### **selectHtmlElement(object)**
+
+This function applies the class attribute defined by `CSS_CLASS_SELECTED` for a given HTML-element. If succeed `true` is returned.
+
+#### **unselectHtmlElement(object)**
+
+This function removes the class attribute defined by `CSS_CLASS_SELECTED` for a given HTML-element. If succeed `true` is returned.
+
+#### **markHtmlElementAsCurrent(object)**
+
+This function applies the class attribute defined by `CSS_CLASS_CURRENT` for a given HTML-element. If succeed `true` is returned.
+
+#### **unmarkHtmlElementAsCurrent(object)**
+
+This function removes the class attribute defined by `CSS_CLASS_CURRENT` for a given HTML-element. If succeed `true` is returned.
+
+#### **activateHtmlElements(args)**
+
+This function enables all HTML-elements listed by `args`.
+
+#### **inactivateHtmlElements(args)**
+
+This function disables all HTML-elements listed by `args`.
+
+### Other functions
+
+#### **valueToClassList(value\[, options])**
+
+This function reads a given value and converts it to an array of a class attributes.
+
+The `options` parameter if sets to `true` force the function to remove all duplicates from its result. The default value is `false`.
+
+### Experimental functions
+
+> Note: Purpose of those functions will be discussed and some may be deprecate and make obsolete or functionality may be altered. So use it with cautions in mind.
+
+#### **createNewHtmlElement(tagName, options)**
+
+This function helps to simplify the process of creating a new HTML-element. It receives the tag name (`tagName` parameter) and the options as a second parameter:
+
+|parameter name|value type|default value|description|
+|:---|---|---:|:---|
+|`tagName`|`string`|`undefined`|defines a tag name of the element.|
+|`options`|`object`|---|contains a set of a settings.|
+
+The `options` structure has listed below:
+
+|option name|value type|default value|description|
+|:---|---|---:|:---|
+|`id`|`string`|`undefined`|defines ID-attribute of an element.|
+|`text`|`string`|`undefined`|defines a text context of an element.|
+|`attr`|---|`undefined`|defines an attributes of an element.|
+|`class`|---|`undefined`|defines a class-attributes of an element.|
+|`data`|---|`undefined`|defines a data-attributes of an element.|
+
+If succeed, the function returned `HTMLElement` and `null` if failed.
+
+This function make all the jobs under the hood. So there is no need to call DOM-object directly in many situations.

package/index.js

@@ -0,0 +1,54 @@
+// [v0.1.009-20220912]
+
+// === module init block ===
+
+const html_helper = require('./lib/html-helper-lib.js');
+const html_list = require('./lib/html-ctrls-list.js');
+const html_bts = require('./lib/html-ctrls-btn.js');
+
+const html_list_btn = require('./lib/html-ctrls/lists-btns.js');
+
+// === module extra block (helper functions) ===
+
+// === module main block ===
+
+// === module exports block ===
+
+exports.CSS_CLASS_STRING = html_helper.CSS_CLASS_STRING;
+exports.isHTMLElement = html_helper.isHTMLElement;
+exports.isCurrentHTMLElement = html_helper.isCurrentHTMLElement;
+exports.isSelectedHTMLElement = html_helper.isSelectedHTMLElement;
+exports.isActiveHTMLElement = html_helper.isActiveHTMLElement;
+exports.isHiddenHTMLElement = html_helper.isHiddenHTMLElement;
+exports.showHtmlElement = html_helper.showHtmlElement;
+exports.hideHtmlElement = html_helper.hideHtmlElement;
+exports.selectHtmlElement = html_helper.selectHtmlElement;
+exports.unselectHtmlElement = html_helper.unselectHtmlElement;
+exports.markHtmlElementAsCurrent = html_helper.markHtmlElementAsCurrent;
+exports.unmarkCurrentHtmlElement = html_helper.unmarkCurrentHtmlElement;
+exports.markHtmlElementAsActive = html_helper.markHtmlElementAsActive;
+exports.unmarkActiveHtmlElement = html_helper.unmarkActiveHtmlElement;
+exports.activateHtmlElements = html_helper.activateHtmlElements;
+exports.inactivateHtmlElements = html_helper.inactivateHtmlElements;
+exports.valueToClassList = html_helper.valueToClassList;
+
+exports.THtmlStubItemsSet = html_list.THtmlStubItemsSet;
+exports.THtmlItemsListContainer = html_list.THtmlItemsListContainer;
+exports.THtmlItemsListController = html_list.THtmlItemsListController;
+
+exports.THtmlButtonsSet = html_bts.THtmlButtonsSet;
+exports.THtmlButtonsControllerARCSet = html_bts.THtmlButtonsControllerARCSet;
+exports.BTS_DEF_GROUP_NAME = html_bts.BTS_DEF_GROUP_NAME;
+
+exports.THtmlListButtonsController = html_list_btn.THtmlListButtonsController;
+
+// experimental
+exports.createNewHtmlElement = html_helper.createNewHtmlElement;
+
+exports.classes = {
+  THtmlStubItemsSet: exports.THtmlStubItemsSet,
+  THtmlItemsListContainer: exports.THtmlItemsListContainer,
+  THtmlItemsListController: exports.THtmlItemsListController,
+  THtmlButtonsSet: exports.THtmlButtonsSet,
+  THtmlListButtonsController: exports.THtmlListButtonsController,
+};