@cntwg/html-helper 0.0.21 → 0.0.23

package/doc/html-helper-lib.md

@@ -1,6 +1,6 @@
->|***rev.*:**|0.1.11|
+>|***rev.*:**|0.1.14|
 >|:---|---:|
->|date:|2023-07-13|
+>|date:|2024-11-10|
 
 ## Introduction
 
@@ -12,139 +12,273 @@ This paper describes a base helpers provided by `html-helper-lib.js` module.
 
 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'|
+| name | value | description |
+|:---|---:|:---|
+| `CSS_CLASS_CURRENT` | 'current' | Marks element as current |
+| `CSS_CLASS_SELECTED` | 'selected' | Marks element as selected |
+| `CSS_CLASS_ACTIVE` | 'active' | Marks element as active |
+| `CSS_CLASS_DISABLED` | 'disabled' | Marks element as disabled |
+| `CSS_CLASS_HIDDEN` | 'hidden' | Marks element as hidden (*not visible on the screen*) |
 
 ## Module functions
 
 ### Logical functions
 
-#### **isHTMLElement(object)**
+<a name="isHTMLElement"></a>
+#### **isHTMLElement(obj)** => `boolean`
 
 This function checks whether or not a given object represents an HTML-element and if so returns `true` or `false` if else.
 
-#### **isSelectedHTMLElement(object)**
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `obj` | `any` | --- | some element to be checked |
+
+<a name="isSelectedHTMLElement"></a>
+#### **isSelectedHTMLElement(obj)** => `boolean`
 
 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)**
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `obj` | `HTMLElement` | --- | some element to be checked |
+
+<a name="isCurrentHTMLElement"></a>
+#### **isCurrentHTMLElement(obj)** => `boolean`
 
 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)**
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `obj` | `HTMLElement` | --- | some element to be checked |
+
+<a name="isActiveHTMLElement"></a>
+#### **isActiveHTMLElement(obj)** => `boolean`
 
 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)**
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `obj` | `HTMLElement` | --- | some element to be checked |
+
+<a name="isHiddenHTMLElement"></a>
+#### **isHiddenHTMLElement(object)** => `boolean`
 
 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`.
 
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `obj` | `HTMLElement` | --- | some element to be checked |
+
 ### Functions for element manipulations
 
-#### **hideHTMLElement(object)**
+<a name="hideHTMLElement"></a>
+#### **hideHTMLElement(obj)** => `boolean`
 
-This function hides HTML-element given by `object` parameter and if succeed `true` is returned.
+This function hides an 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.
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `obj` | `HTMLElement` | --- | some element to be modified |
 
-#### **showHTMLElement(object)**
+> Note: Technically, the function provide a wrapper that applies the class attribute defined by 'CSS_CLASS_HIDDEN' for a given HTML-element.
 
-This function unhides HTML-element given by `object` parameter and if succeed `true` is returned.
+<a name="showHTMLElement"></a>
+#### **showHTMLElement(obj)** => `boolean`
 
-> Note: Technicly, the function provide a wrapper that removes the class attribute defined by 'CSS_CLASS_HIDDEN' for a given HTML-element.
+This function unhides an HTML-element given by `object` parameter and if succeed `true` is returned.
 
-#### **selectHtmlElement(object)**
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `obj` | `HTMLElement` | --- | some element to be modified |
+
+> Note: Technically, the function provide a wrapper that removes the class attribute defined by 'CSS_CLASS_HIDDEN' for a given HTML-element.
+
+<a name="selectHTMLElement"></a>
+#### **selectHTMLElement(obj)** => `boolean`
 
 This function applies the class attribute defined by `CSS_CLASS_SELECTED` for a given HTML-element. If succeed `true` is returned.
 
-#### **unselectHtmlElement(object)**
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `obj` | `HTMLElement` | --- | some element to be modified |
+
+<a name="unselectHTMLElement"></a>
+#### **unselectHTMLElement(obj)** => `boolean`
 
 This function removes the class attribute defined by `CSS_CLASS_SELECTED` for a given HTML-element. If succeed `true` is returned.
 
-#### **markHtmlElementAsCurrent(object)**
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `obj` | `HTMLElement` | --- | some element to be modified |
+
+<a name="markHTMLElementAsCurrent"></a>
+#### **markHTMLElementAsCurrent(obj)** => `boolean`
 
 This function applies the class attribute defined by `CSS_CLASS_CURRENT` for a given HTML-element. If succeed `true` is returned.
 
-#### **unmarkHtmlElementAsCurrent(object)**
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `obj` | `HTMLElement` | --- | some element to be modified |
+
+<a name="unmarkCurrentHTMLElement"></a>
+#### **unmarkCurrentHTMLElement(obj)** => `boolean`
 
 This function removes the class attribute defined by `CSS_CLASS_CURRENT` for a given HTML-element. If succeed `true` is returned.
 
-#### **unlockHtmlElement(object)**
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `obj` | `HTMLElement` | --- | some element to be modified |
 
-> since: `v0.0.19`
+<a name="markHTMLElementAsActive"></a>
+#### **markHTMLElementAsActive(obj)** => `boolean`
 
-This function enables a given HTML-element.
+This function applies the class attribute defined by `CSS_CLASS_ACTIVE` for a given HTML-element. If succeed `true` is returned.
+
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `obj` | `HTMLElement` | --- | some element to be modified |
+
+<a name="unmarkActiveHTMLElement"></a>
+#### **unmarkActiveHTMLElement(obj)** => `boolean`
+
+This function removes the class attribute defined by `CSS_CLASS_ACTIVE` for a given HTML-element. If succeed `true` is returned.
+
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `obj` | `HTMLElement` | --- | some element to be modified |
 
-#### **lockHtmlElement(args)**
+<a name="lockHTMLElement"></a>
+#### **lockHTMLElement(obj)** => `boolean`
 
 > since: `v0.0.19`
 
 This function disables a given HTML-element.
 
-#### **activateHtmlElements(args)**
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `obj` | `HTMLElement` | --- | some element to be modified |
+
+<a name="unlockHTMLElement"></a>
+#### **unlockHTMLElement(obj)** => `boolean`
+
+> since: `v0.0.19`
 
-This function enables all HTML-elements listed by `args`.
+This function enables a given HTML-element.
+
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `obj` | `HTMLElement` | --- | some element to be modified |
 
-#### **inactivateHtmlElements(args)**
+<a name="activateHTMLElements"></a>
+#### **activateHtmlElements(arg_1\[, arg_2\[, ...arg_N]])** => `void`
 
-This function disables all HTML-elements listed by `args`.
+This function enables all HTML-elements received as a function arguments.
+
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `arg_[1...N]` | `HTMLElement` | --- | some element to be modified |
+
+<a name="inactivateHTMLElements"></a>
+#### **inactivateHTMLElements(arg_1\[, arg_2\[, ...arg_N]])** => `void`
+
+This function disables all HTML-elements received as a function arguments.
+
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `arg_[1...N]` | `HTMLElement` | --- | some element to be modified |
 
 ### Other functions
 
-#### **valueToClassList(value\[, options])**
+<a name="valueToClassList"></a>
+#### **valueToClassList(value\[, options])** => `string[]`
+
+> since: `v0.0.13`
 
 This function reads a given value and converts it to an array of a class attributes.
 
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `value` | `any` | --- | some value |
+| `options` | `boolean` | --- | some value |
+
 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.
 
+<a name="createNewHtmlElement"></a>
 #### **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|
+| 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|
+| `tagName` | `string` | --- | defines a tag name of the element |
+| `options` | `object` | `undefined` | contains a set of a settings |
 
-The `options` structure has listed below:
+The `options` parameter structure has listed below:
 
-|option name|value type|default value|description|
+| 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|
-|`classNames`|---|`undefined`|defines a class-attributes of an element (*`since: v0.0.19`*)|
-|`data`|---|`undefined`|defines a data-attributes of an element|
+| `id` | `string` | `undefined` | defines an ID-attribute of an element |
+| `text` | `string` | `undefined` | defines a text context of an element |
+| `attr` | `object` | --- | defines an attributes of an element |
+| `classNames` | `string`, `string[]` | `undefined` | defines a class-attributes of an element (*`since: v0.0.19`*) |
+| `data` | `object` | --- | 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.
 
-#### **valueToIDString(value)**
+<a name="valueToIDString"></a>
+#### **valueToIDString(value\[, options])** => `?string`
+
+This function tries to convert a given `value` to `ID_STRING`. If failed a `null` is returned.
+
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `value` | `any` | --- | some value |
+| `options` | `boolean`, `object` | --- | options to set constraints |
 
-This function tries to convert a given `value` to `ID_STRING`. If failed an empty string is returned.
+> NOTE: This is a re-exported function. For more details see docs for [`@ygracs/bsfoc-lib-js`](https://gitlab.com/ygracs/bsfoc-lib-js)-module.
 
-#### **readAsTagName(value)**
+<a name="readAsTagName"></a>
+#### **readAsTagName(value)** => `string`
 
 > since: `v0.0.21`
 
 This function tries to convert a given `value` to the value of type which is suitable for an HTML-element's tag name. If failed an empty string is returned.
 
-#### **readAsAttrName(value)**
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `value` | `any` | --- | some value |
+
+<a name="readAsAttrName"></a>
+#### **readAsAttrName(value)** => `string`
 
 > since: `v0.0.21`
 
 This function tries to convert a given `value` to the value of type which is suitable for an HTML-element's attribute name. If failed an empty string is returned.
 
-#### **readAsAttrValue(value)**
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `value` | `any` | --- | some value |
+
+<a name="readAsAttrValue"></a>
+#### **readAsAttrValue(value)** => `string`
+
+> since: `v0.0.18`
 
 This function tries to convert a given `value` to the value of type which is suitable for an HTML-element's attribute. If failed a `null` is returned.
+
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `value` | `any` | --- | some value |
+
+<a name="valueToElementID"></a>
+#### **valueToElementID(value)** => `string`
+
+> since: `v0.0.22`
+
+This function tries to convert a given `value` to the value of a valid identifier which is suitable for an HTML-element's ID-attribute. If failed an empty string is returned.

package/index.js

@@ -1,4 +1,4 @@
-// [v0.1.019-20240713]
+// [v0.1.025-20241115]
 
 // === module init block ===
 
@@ -7,6 +7,7 @@ const html_list = require('./lib/html-ctrls/list.js');
 const html_list_btn = require('./lib/html-ctrls/lists-btn.js');
 const html_bts = require('./lib/html-ctrls/buttons.js');
 const html_flds = require('./lib/html-ctrls/fields.js');
+const ev_helper = require('./lib/event-hfunc.js');
 
 
 // === module extra block (helper functions) ===
@@ -24,6 +25,11 @@ const components = {
   THtmlInputField: html_flds.THtmlInputField,
 };
 
+const eventHelper = {
+  pushEventHandler: ev_helper.pushEventHandler,
+  triggerEventHandler: ev_helper.triggerEventHandler,
+};
+
 // === module exports block ===
 
 module.exports.CSS_CLASS_STRING = html_helper.CSS_CLASS_STRING;
@@ -32,27 +38,27 @@ module.exports.isSelectedHTMLElement = html_helper.isSelectedHTMLElement;
 module.exports.isCurrentHTMLElement = html_helper.isCurrentHTMLElement;
 module.exports.isActiveHTMLElement = html_helper.isActiveHTMLElement;
 module.exports.isHiddenHTMLElement = html_helper.isHiddenHTMLElement;
-module.exports.hideHtmlElement = html_helper.hideHtmlElement;
-module.exports.showHtmlElement = html_helper.showHtmlElement;
-module.exports.selectHtmlElement = html_helper.selectHtmlElement;
-module.exports.unselectHtmlElement = html_helper.unselectHtmlElement;
-module.exports.markHtmlElementAsCurrent = html_helper.markHtmlElementAsCurrent;
-module.exports.unmarkCurrentHtmlElement = html_helper.unmarkCurrentHtmlElement;
-module.exports.markHtmlElementAsActive = html_helper.markHtmlElementAsActive;
-module.exports.unmarkActiveHtmlElement = html_helper.unmarkActiveHtmlElement;
-module.exports.lockHtmlElement = html_helper.lockHtmlElement;
-module.exports.unlockHtmlElement = html_helper.unlockHtmlElement;
-module.exports.inactivateHtmlElements = html_helper.inactivateHtmlElements;
-module.exports.activateHtmlElements = html_helper.activateHtmlElements;
+module.exports.hideHTMLElement = html_helper.hideHTMLElement;
+module.exports.showHTMLElement = html_helper.showHTMLElement;
+module.exports.selectHTMLElement = html_helper.selectHTMLElement;
+module.exports.unselectHTMLElement = html_helper.unselectHTMLElement;
+module.exports.markHTMLElementAsCurrent = html_helper.markHTMLElementAsCurrent;
+module.exports.unmarkCurrentHTMLElement = html_helper.unmarkCurrentHTMLElement;
+module.exports.markHTMLElementAsActive = html_helper.markHTMLElementAsActive;
+module.exports.unmarkActiveHTMLElement = html_helper.unmarkActiveHTMLElement;
+module.exports.lockHTMLElement = html_helper.lockHTMLElement;
+module.exports.unlockHTMLElement = html_helper.unlockHTMLElement;
+module.exports.activateHTMLElements = html_helper.activateHTMLElements;
+module.exports.inactivateHTMLElements = html_helper.inactivateHTMLElements;
 module.exports.valueToClassList = html_helper.valueToClassList;
 
 module.exports.THtmlStubItemsSet = html_list.THtmlStubItemsSet;
 module.exports.THtmlItemsListContainer = html_list.THtmlItemsListContainer;
 module.exports.THtmlItemsListController = html_list.THtmlItemsListController;
 
+module.exports.BTS_DEF_GROUP_NAME = html_bts.BTS_DEF_GROUP_NAME;
 module.exports.THtmlButtonsSet = html_bts.THtmlButtonsSet;
 module.exports.THtmlButtonsControllerARCSet = html_bts.THtmlButtonsControllerARCSet;
-module.exports.BTS_DEF_GROUP_NAME = html_bts.BTS_DEF_GROUP_NAME;
 
 module.exports.THtmlListButtonsController = html_list_btn.THtmlListButtonsController;
 
@@ -62,13 +68,32 @@ module.exports.components = components;
 module.exports.readAsTagName = html_helper.readAsTagName;
 module.exports.readAsAttrName = html_helper.readAsAttrName;
 module.exports.readAsAttrValue = html_helper.readAsAttrValue;
+module.exports.valueToElementID = html_helper.valueToElementID;
 module.exports.createNewHtmlElement = html_helper.createNewHtmlElement;
 
+module.exports.isHTMLButton = html_bts.isHTMLButton;
+
 module.exports.THtmlInputField = html_flds.THtmlInputField;
 
+module.exports.eventHelper = eventHelper;
+
 // re-exported
 module.exports.valueToIDString = html_helper.valueToIDString;
 
 // will deprecate
+module.exports.classes = components;
+
+// deprecated
 module.exports.component = components;
-module.exports.classes = exports.component;
+module.exports.hideHtmlElement = html_helper.hideHtmlElement;
+module.exports.showHtmlElement = html_helper.showHtmlElement;
+module.exports.selectHtmlElement = html_helper.selectHtmlElement;
+module.exports.unselectHtmlElement = html_helper.unselectHtmlElement;
+module.exports.markHtmlElementAsCurrent = html_helper.markHtmlElementAsCurrent;
+module.exports.unmarkCurrentHtmlElement = html_helper.unmarkCurrentHtmlElement;
+module.exports.markHtmlElementAsActive = html_helper.markHtmlElementAsActive;
+module.exports.unmarkActiveHtmlElement = html_helper.unmarkActiveHtmlElement;
+module.exports.lockHtmlElement = html_helper.lockHtmlElement;
+module.exports.unlockHtmlElement = html_helper.unlockHtmlElement;
+module.exports.inactivateHtmlElements = html_helper.inactivateHtmlElements;
+module.exports.activateHtmlElements = html_helper.activateHtmlElements;

package/lib/event-hfunc.js

@@ -0,0 +1,60 @@
+// [v0.1.062-20241115]
+
+// === module init block ===
+
+// === module extra block (helper functions) ===
+
+// === module main block ===
+
+/***
+ * (* constant definitions *)
+ */
+
+/***
+ * (* function definitions *)
+ */
+
+/**
+ * @function pushEventHandler
+ * @param {object} pool - pool object
+ * @param {string} name - event name
+ * @param {func} evnt - callback function
+ * @returns {void}
+ * @inner
+ */
+function pushEventHandler(pool, name, evnt){
+  const _name = typeof name === 'string' ? name.trim() : '';
+  if (_name !== '' && typeof evnt === 'function') {
+    if (!pool.has(_name)) {
+      pool.set(_name, evnt);
+    } else {
+      /* NOTE:
+       *    for current you can't reset or set new one on the same event
+       */
+    };
+  };
+};
+
+/**
+ * @function triggerEventHandler
+ * @param {object} pool - pool object
+ * @param {string} name - event name
+ * @param {...any} [args]
+ * @returns {void}
+ * @inner
+ */
+function triggerEventHandler(pool, name, ...args){
+  const _name = typeof name === 'string' ? name.trim() : '';
+  if (_name !== '') {
+    if (pool.has(_name)) pool.get(_name)(...args);
+  };
+};
+
+/***
+ * (* class definitions *)
+ */
+
+// === module exports block ===
+
+exports.pushEventHandler = pushEventHandler;
+exports.triggerEventHandler = triggerEventHandler;