@cntwg/html-helper 0.0.20 → 0.0.21

package/CHANGELOG.md

@@ -1,3 +1,16 @@
+#### *v0.0.21*
+
+Pre-release version.
+
+> - `html-ctrls-list.md` updated;
+> - `html-ctrls-fields.md` updated;
+> - `html-ctrls-btn.md` updated;
+> - updated dependency on `@ygracs/bsfoc-lib-js` module to v0.2.1;
+> - remove some deprecates (*see docs for details*);
+> - change behavior for `loadItems` method of `THtmlStubItemsSet` class in handling `options` parameter (*see docs for details*);
+> - added 'components' property for module exports;
+> - some other fixes.
+
 #### *v0.0.20*
 
 Pre-release version.

package/LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2019-2023 Yuri Grachev
+Copyright (c) 2019-2024 Yuri Grachev
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 

package/README.md

@@ -1,41 +1,42 @@
->|***rev.*:**|0.1.4|
+>|***rev.*:**|0.1.5|
 >|:---|---:|
->|date:|2023-06-29|
+>|date:|2024-07-13|
 
 ## Introduction
 
 This module provide a base set of helpers for javascript. So your work can run a bit easy by using it when you deal with HTML-forms.
 
-## Use cases
-
-This module was make for use as a library in a development of a Web-apps based on [Electron](https://en.wikipedia.org/wiki/Electron_(software_framework)) as main target.
-
-### Installation
-
-`npm install @cntwg/html-helper`
-
 ## Description
 
 This module contains the following components:
 
-- base helper module which provided a set of constants and functions usefull for some manipulation with HTML-elements.
+- base helper module which provided a set of constants and functions useful for some manipulation with HTML-elements.
 
 > *For more details see `html-helper.md` in module `doc` directory*.
 
-- class `THtmlButtonsSet`,
-- class `THtmlListButtonsController`,
-- class `THtmlButtonsControllerARCSet`.
+- classes for working with instances maintaining a buttons set support such as:
+  - `THtmlButtonsSet`,
+	- `THtmlListButtonsController`,
+	- `THtmlButtonsControllerARCSet`.
 
 > *For more details see `html-ctrls-btn.md` in module `doc` directory*.
 
-- classes for working with HTML-elements maintaining a lists support such as:
+- classes for working with instances maintaining a lists support such as:
 	- `THtmlItemsListContainer`,
 	- `THtmlItemsListController`,
 	- `THtmlStubItemsSet`.
 
 > *For more details see `html-ctrls-list.md` in module `doc` directory*.
 
-- classes for working with HTML-elements maintaining an input fields support such as:
+- classes for working with instances maintaining an input fields support such as:
 	- `THtmlInputField` (experimental, beta stage).
 
 > *For more details see `html-ctrls-fields.md` in module `doc` directory*.
+
+## Use cases
+
+This module was make for use as a library in a development of a Web-apps based on [Electron](https://en.wikipedia.org/wiki/Electron_(software_framework)) as main target.
+
+### Installation
+
+`npm install @cntwg/html-helper`

package/doc/html-ctrls-btn.md

@@ -1,6 +1,6 @@
->|***rev.*:**|0.1.9|
+>|***rev.*:**|0.1.11|
 >|:---|---:|
->|date:|2023-07-04|
+>|date:|2024-07-13|
 
 ## Introduction
 
@@ -22,7 +22,11 @@ This class provide a manageable collection which used to group buttons placed on
 
 #### class constructor
 
-The class constructor creates a new instance of the class. No arguments is receives by it.
+The class constructor creates a new instance of the class.
+
+##### constructor parameters
+
+The class constructor receives no arguments.
 
 #### class properties
 
@@ -103,19 +107,18 @@ This class provide a buttons controller to use with a list components to perform
 
 #### class constructor
 
-The class constructor creates a new instance of the class. It receives an `options` parameter which structure has listed below:
+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`|---|define HTML-button which will select the first element|
-|`btn_frst`|`HTMLElement`|---|\<*deprecate*> *(use `btnFirst` instead)*|
 |`btnPrev`|`HTMLElement`|---|define HTML-button which will select the previous element|
-|`btn_prev`|`HTMLElement`|---|\<*deprecate*> *(use `btnPrev` instead)*|
 |`btnNext`|`HTMLElement`|---|define HTML-button which will select the next element|
-|`btn_next`|`HTMLElement`|---|\<*deprecate*> *(use `btnNext` instead)*|
 |`btnLast`|`HTMLElement`|---|define HTML-button which will select the last element|
-|`btn_last`|`HTMLElement`|---|\<*deprecate*> *(use `btnLast` instead)*|
-
 
 #### class properties
 
@@ -172,7 +175,11 @@ This class provide a buttons controller to use with a form components to perform
 
 #### class constructor
 
-The class constructor creates a new instance of the class. It receives an `options` parameter which structure has listed below:
+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|
 |:---|---|---:|:---|

package/doc/html-ctrls-fields.md

@@ -1,6 +1,6 @@
->|***rev.*:**|0.0.4|
+>|***rev.*:**|0.0.5|
 >|:---|---:|
->|date:|2023-07-04|
+>|date:|2023-10-05|
 
 ## Introduction
 
@@ -14,7 +14,11 @@ This class provide a container useful when dealing with an elements such an inpu
 
 #### class constructor
 
-The class constructor creates a new instance of the class. It receives a parameters listed below:
+The class constructor creates a new instance of the class.
+
+##### constructor parameters
+
+The class constructor receives a parameters listed below:
 
 |parameter name|value type|default value|description|
 |:---|---|---:|:---|
@@ -22,6 +26,8 @@ The class constructor creates a new instance of the class. It receives a paramet
 |`eholds`|`object`|---|contains ref-list for container elements|
 |`options`|`object`|---|contains a container settings|
 
+##### `eholds` parameter
+
 The `eholds` structure has listed below:
 
 |parameter name|value type|default value|description|
@@ -30,6 +36,8 @@ The `eholds` structure has listed below:
 |`label`|`HTMLElement`|---|points to a label item|
 |`field`|`HTMLElement`|---|points to a field item|
 
+##### `options` parameter
+
 The `options` structure has listed below:
 
 |option name|value type|default value|description|

package/doc/html-ctrls-list.md

@@ -1,6 +1,6 @@
->|***rev.*:**|0.1.15|
+>|***rev.*:**|0.1.18|
 >|:---|---:|
->|date:|2023-07-04|
+>|date:|2023-11-19|
 
 ## Introduction
 
@@ -14,13 +14,19 @@ This class provide a base container useful when dealing with a list elements pla
 
 #### class constructor
 
-The class constructor creates a new instance of the class. It receives a parameters listed below:
+The class constructor creates a new instance of the class.
+
+##### constructor parameters
+
+The class constructor 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|
 
+##### `options` parameter
+
 The `options` structure has listed below:
 
 |option name|value type|default value|description|
@@ -153,13 +159,19 @@ This class implements a controller that provide mechanism for managing a list co
 
 #### class constructor
 
-The class constructor creates a new instance of the class. It receives a parameters listed below:
+The class constructor creates a new instance of the class.
+
+##### constructor parameters
+
+The class constructor 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|
 
+##### `options` parameter
+
 The `options` structure has listed below:
 
 |option name|value type|default value|description|
@@ -169,7 +181,7 @@ The `options` structure has listed below:
 |`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*>|
+|`allowSelectionLocks`|`boolean`|`false`|\<*reserved, experimental*>|
 
 #### class properties
 
@@ -311,12 +323,26 @@ This class implements a controller that provide mechanism for managing a so-call
 
 #### class constructor
 
-The class constructor creates a new instance of the class. It receives a parameters listed below:
+The class constructor creates a new instance of the class.
+
+##### constructor parameters
+
+The class constructor 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|
+|`options`|`object` or `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|
+|:---|---|---:|:---|
+|`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|
 
 #### class properties
 
@@ -409,7 +435,6 @@ The `options` parameter is an `object` that contains the following set of parame
 |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`|\<*deprecate*> *(use `useClear` instead)*|
 |`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.

package/doc/html-helper-lib.md

@@ -1,6 +1,6 @@
->|***rev.*:**|0.1.8|
+>|***rev.*:**|0.1.11|
 >|:---|---:|
->|date:|2023-06-12|
+>|date:|2023-07-13|
 
 ## Introduction
 
@@ -76,10 +76,14 @@ This function removes the class attribute defined by `CSS_CLASS_CURRENT` for a g
 
 #### **unlockHtmlElement(object)**
 
+> since: `v0.0.19`
+
 This function enables a given HTML-element.
 
 #### **lockHtmlElement(args)**
 
+> since: `v0.0.19`
+
 This function disables a given HTML-element.
 
 #### **activateHtmlElements(args)**
@@ -118,8 +122,7 @@ The `options` structure has listed below:
 |`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`|\<deprecate> (*use `classNames` instead*)|
-|`classNames`|---|`undefined`|defines a class-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|
 
 If succeed, the function returned `HTMLElement` and `null` if failed.
@@ -130,6 +133,18 @@ This function make all the jobs under the hood. So there is no need to call DOM-
 
 This function tries to convert a given `value` to `ID_STRING`. If failed an empty string is returned.
 
+#### **readAsTagName(value)**
+
+> 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)**
+
+> 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)**
 
 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.

package/index.js

@@ -1,67 +1,74 @@
-// [v0.1.018-20230629]
+// [v0.1.019-20240713]
 
 // === module init block ===
 
 const html_helper = require('./lib/html-helper-lib.js');
 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 html_list_btn = require('./lib/html-ctrls/lists-btn.js');
 
 // === module extra block (helper functions) ===
 
 // === module main block ===
 
+const components = {
+  THtmlStubItemsSet: html_list.THtmlStubItemsSet,
+  THtmlItemsListContainer: html_list.THtmlItemsListContainer,
+  THtmlItemsListController: html_list.THtmlItemsListController,
+  THtmlButtonsSet: html_bts.THtmlButtonsSet,
+  THtmlButtonsControllerARCSet: html_bts.THtmlButtonsControllerARCSet,
+  THtmlListButtonsController: html_list_btn.THtmlListButtonsController,
+  // experimental
+  THtmlInputField: html_flds.THtmlInputField,
+};
+
 // === 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.lockHtmlElement = html_helper.lockHtmlElement;
-exports.unlockHtmlElement = html_helper.unlockHtmlElement;
-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;
+module.exports.CSS_CLASS_STRING = html_helper.CSS_CLASS_STRING;
+module.exports.isHTMLElement = html_helper.isHTMLElement;
+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.valueToClassList = html_helper.valueToClassList;
 
-// experimental
-exports.THtmlInputField = html_flds.THtmlInputField;
+module.exports.THtmlStubItemsSet = html_list.THtmlStubItemsSet;
+module.exports.THtmlItemsListContainer = html_list.THtmlItemsListContainer;
+module.exports.THtmlItemsListController = html_list.THtmlItemsListController;
+
+module.exports.THtmlButtonsSet = html_bts.THtmlButtonsSet;
+module.exports.THtmlButtonsControllerARCSet = html_bts.THtmlButtonsControllerARCSet;
+module.exports.BTS_DEF_GROUP_NAME = html_bts.BTS_DEF_GROUP_NAME;
 
-exports.THtmlListButtonsController = html_list_btn.THtmlListButtonsController;
+module.exports.THtmlListButtonsController = html_list_btn.THtmlListButtonsController;
+
+module.exports.components = components;
 
 // experimental
-exports.valueToIDString = html_helper.valueToIDString;
-exports.readAsAttrValue = html_helper.readAsAttrValue;
-exports.createNewHtmlElement = html_helper.createNewHtmlElement;
-
-exports.component = {
-  THtmlStubItemsSet: exports.THtmlStubItemsSet,
-  THtmlItemsListContainer: exports.THtmlItemsListContainer,
-  THtmlItemsListController: exports.THtmlItemsListController,
-  THtmlButtonsSet: exports.THtmlButtonsSet,
-  THtmlListButtonsController: exports.THtmlListButtonsController,
-  THtmlButtonsControllerARCSet: exports.THtmlButtonsControllerARCSet,
-  // experimental
-  THtmlInputField: exports.THtmlInputField,
-};
+module.exports.readAsTagName = html_helper.readAsTagName;
+module.exports.readAsAttrName = html_helper.readAsAttrName;
+module.exports.readAsAttrValue = html_helper.readAsAttrValue;
+module.exports.createNewHtmlElement = html_helper.createNewHtmlElement;
+
+module.exports.THtmlInputField = html_flds.THtmlInputField;
+
+// re-exported
+module.exports.valueToIDString = html_helper.valueToIDString;
+
 // will deprecate
-exports.classes = exports.component;
+module.exports.component = components;
+module.exports.classes = exports.component;