@cntwg/html-helper 0.0.17 → 0.0.19

package/CHANGELOG.md

@@ -0,0 +1,176 @@
+#### *v0.0.19*
+
+Pre-release version.
+
+> - `html-helper-lib.md` updated;
+> - updated dependency on `@ygracs/bsfoc-lib-js` module to v0.1.3;
+> - add functions `lockHtmlElement` and `unlockHtmlElement` into `html-helper-lib.js` module;
+> - change behavior for `createNewHtmlElement` function in handling `options` parameter (*see docs for details*);
+> - added `THtmlInputField` class (experimental);
+> - some other fixes.
+
+#### *v0.0.18*
+
+Pre-release version.
+
+> - `html-helper-lib.md` updated;
+> - some fixes in `html-helper-lib.js` module;
+> - add `mod-hfunc.js` module;
+> - rename module `html-ctrls-list.js` to `html-ctrls/list.js`;
+> - some fixes in `list.js` module;
+> - rename module `html-ctrls-btn.js` to `html-ctrls/buttons.js`;
+> - some fixes in `buttons.js` module;
+> - some fixes in `lists-btn.js` module;
+> - some fixes in `lists-stubs.js` module;
+> - add function `readAsAttrValue` into `html-helper-lib.js` module;
+> - add settings `itemBaseClassID` to `THtmlItemsListContainer` class constructor `options` parameter;
+> - added 'component' property for module exports;
+> - deprecated  'classes' property for module exports (*use `component` instead*);
+
+#### *v0.0.17*
+
+Pre-release version.
+
+> improved event logic on items deletion for `THtmlItemsListController` class.
+
+#### *v0.0.16*
+
+Pre-release version.
+
+> improved items selection logic for `THtmlItemsListController` class.
+
+#### *v0.0.15*
+
+Pre-release version.
+
+> - `html-helper-lib.md` updated;
+> - `html-ctrls-list.md` updated;
+> - some fixes in `html-ctrls-btn.js` module;
+> - some fixes in `html-ctrls-list.js` module;
+> - alter behavior for the `srchIndexByAttr` method of a `THtmlItemsListContainer` class (*see docs for details*);
+> - add settings `markCurrentItem` to `THtmlItemsListContainer` class constructor `options` parameter;
+> - add function `valueToIDString` into `html-helper-lib.js` module;
+
+#### *v0.0.14*
+
+Pre-release version.
+
+> - `html-ctrls-list.md` updated;
+> - some fixes in `html-ctrls/list-stubs.js` module;
+> - alter behavior for the `loadItems` method of a `THtmlStubItemsSet` class in case when its `options` parameter is set to `boolean` (see `html-ctrls-list.md` for details);
+> - added method `rstDefItem` to `THtmlStubItemsSet` class;
+> - added `THtmlButtonsControllerARCSet` class.
+
+#### *v0.0.13*
+
+Pre-release version.
+
+> - `html-helper-lib.md` updated;
+> - `html-ctrls-btn.md` updated;
+> - `html-ctrls-list.md` updated;
+> - some fixes in `html-helper-lib.js` module;
+> - some fixes in `html-ctrls-btn.js` module;
+> - some fixes in `html-ctrls-list.js` module;
+> - move definition of `THtmlStubItemsSet` from `html-ctrls-list.js` module to `html-ctrls/lists-stubs.js` submodule;
+> - add function `valueToClassList` into `html-helper-lib.js` module;
+> - updated dependency on `@ygracs/bsfoc-lib-js` module to v0.1.2.
+
+#### *v0.0.12*
+
+Pre-release version.
+
+> - updated dependency on `@ygracs/bsfoc-lib-js` module to v0.1.1.
+
+#### *v0.0.11*
+
+Pre-release version.
+
+> - `html-ctrls-btn.md` updated;
+> - `html-ctrls-list.md` updated;
+> - some fixes in `html-ctrls-list.js` module;
+> - some fixes in `html-ctrls-btn.js` module.
+
+#### *v0.0.10*
+
+Pre-release version.
+
+> - `html-ctrls-btn.md` updated;
+> - added `THtmlListButtonsController` class;
+
+#### *v0.0.9*
+
+Pre-release version.
+
+> - switch dependency from `@cntwg/bsfoc-lib-js` module to `@ygracs/bsfoc-lib-js` module.
+
+#### *v0.0.8*
+
+Pre-release version.
+
+> - updated dependency on `@cntwg/bsfoc-lib-js` module to v0.0.11.
+
+#### *v0.0.7*
+
+Pre-release version.
+
+> - updated dependency on `@cntwg/bsfoc-lib-js` module to v0.0.10;
+> - some fixes in `html-helper-lib.js` module;
+> - some fixes in `html-ctrls-list.js` module.
+
+#### *v0.0.6*
+
+Pre-release version.
+
+> - `html-ctrls-btn.md` updated;
+> - `html-ctrls-list.md` updated;
+> - `html-helper-lib.md` updated;
+> - some fixes in `html-ctrls-btn.js` module;
+> - some fixes in `html-ctrls-list.js` module.
+
+#### *v0.0.5*
+
+Pre-release version.
+
+> - `$module/test/README.md` added;
+> - updated dependency on `@cntwg/bsfoc-lib-js` module to v0.0.8;
+> - `html-ctrls-list.md` updated;
+> - added `minIndex` property to `THtmlItemsListContainer` class;
+> - some fixes in `html-ctrls-list.js` module;
+> - added 'classes' property for module exports;
+> - MIT-license applied.
+
+#### *v0.0.4*
+
+Pre-release version.
+
+> - updated dependency on `@cntwg/bsfoc-lib-js` module to v0.0.5.
+
+#### *v0.0.3*
+
+Pre-release version.
+
+> - added `activateHTMLElements` function;
+> - added `inactivateHTMLElements` function;
+> - added `createNewHtmlElement` function (experimental);
+> - `html-helper-lib.md` updated;
+> - `html-ctrls-btn.md` updated;
+> - `html-ctrls-list.md` updated.
+
+#### *v0.0.2*
+
+Pre-release version.
+
+> - `README.md` added;
+> - `html-helper-lib.md` added to `doc`;
+> - `html-ctrls-btn.md` added to `doc`;
+> - `html-ctrls-list.md` added to `doc`;
+> - added `CSS_CLASS_ACTIVE` constant to `CSS_CLASS_STRING`;
+> - added `isActiveHTMLElement` function;
+> - added `markHtmlElementAsActive` function;
+> - added `unmarkActiveHtmlElement` function;
+> - `html-btn-ctrl.js` was renamed `html-ctrls-btn.js`;
+> - `html-list-ctrl.js` was renamed `html-ctrls-list.js`.
+
+#### *v0.0.1*
+
+Pre-release version.

package/LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2019-2022 Yuri Grachev
+Copyright (c) 2019-2023 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,6 +1,6 @@
->|***rev.*:**|0.1.2|
+>|***rev.*:**|0.1.4|
 >|:---|---:|
->|date:|2022-09-12|
+>|date:|2023-06-29|
 
 ## Introduction
 
@@ -10,6 +10,10 @@ This module provide a base set of helpers for javascript. So your work can run a
 
 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:
@@ -30,3 +34,8 @@ This module contains the following components:
 	- `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:
+	- `THtmlInputField` (experimental, beta stage).
+
+> *For more details see `html-ctrls-fields.md` in module `doc` directory*.

package/doc/html-ctrls-btn.md

@@ -1,6 +1,6 @@
->|***rev.*:**|0.1.8|
+>|***rev.*:**|0.1.9|
 >|:---|---:|
->|date:|2022-09-12|
+>|date:|2023-07-04|
 
 ## Introduction
 
@@ -77,7 +77,7 @@ This method adds a group given by `name`. If succeed `true` is returned.
 
 ##### **delGroup(name)**
 
-This method deletes the gpoup given by `name`. If succeed `true` is returned.
+This method deletes the group given by `name`. If succeed `true` is returned.
 
 ##### **renameGroup(oldName, newName)**
 
@@ -108,13 +108,13 @@ The class constructor creates a new instance of the class. It receives an `optio
 |option name|option type|default value|description|
 |:---|---|---:|:---|
 |`btnFirst`|`HTMLElement`|---|define HTML-button which will select the first element|
-|`btn_frst`|`HTMLElement`|---|*will deprecate (use `btnFirst` instead)*|
+|`btn_frst`|`HTMLElement`|---|\<*deprecate*> *(use `btnFirst` instead)*|
 |`btnPrev`|`HTMLElement`|---|define HTML-button which will select the previous element|
-|`btn_prev`|`HTMLElement`|---|*will deprecate (use `btnPrev` instead)*|
+|`btn_prev`|`HTMLElement`|---|\<*deprecate*> *(use `btnPrev` instead)*|
 |`btnNext`|`HTMLElement`|---|define HTML-button which will select the next element|
-|`btn_next`|`HTMLElement`|---|*will deprecate (use `btnNext` instead)*|
+|`btn_next`|`HTMLElement`|---|\<*deprecate*> *(use `btnNext` instead)*|
 |`btnLast`|`HTMLElement`|---|define HTML-button which will select the last element|
-|`btn_last`|`HTMLElement`|---|*will deprecate (use `btnLast` instead)*|
+|`btn_last`|`HTMLElement`|---|\<*deprecate*> *(use `btnLast` instead)*|
 
 
 #### class properties

package/doc/html-ctrls-fields.md

@@ -0,0 +1,140 @@
+>|***rev.*:**|0.0.4|
+>|:---|---:|
+>|date:|2023-07-04|
+
+## Introduction
+
+This paper describes a classes provided by `html-ctrls-fields.js` module.
+
+## Module classes
+
+### **THtmlInputField**
+
+This class provide a container useful when dealing with an elements such an input fields or a checkboxes 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|
+|:---|---|---:|:---|
+|`name`|`string`|---|\<*reserved*>|
+|`eholds`|`object`|---|contains ref-list for container elements|
+|`options`|`object`|---|contains a container settings|
+
+The `eholds` structure has listed below:
+
+|parameter name|value type|default value|description|
+|:---|---|---:|:---|
+|`host`|`HTMLElement`|---|points to a host element which holds all other items|
+|`label`|`HTMLElement`|---|points to a label item|
+|`field`|`HTMLElement`|---|points to a field item|
+
+The `options` structure has listed below:
+
+|option name|value type|default value|description|
+|:---|---|---:|:---|
+|`idPref`|---|---|\<*reserved*>|
+|`baseClassID`|---|---|\<*reserved*>|
+|`hint`|---|---|\<*reserved*>|
+|`fldType`|---|---|\<*reserved*>|
+|`isReadOnly`|---|---|\<*reserved*>|
+
+#### class properties
+
+The table below describes a properties of a `THtmlInputField` class:
+
+|property name|property type|read only|description|
+|:---|---|---|:---|
+|`value`|`string` or `boolean`|no|contains a container value|
+|`isModified`|`boolean`|yes|show whether or not the field content was modified|
+
+#### class methods
+
+##### **clear()**
+
+> Note: \<*reserved*>
+
+##### **isEmpty()**
+
+This method returns `true` if the container field element contains an empty string.
+
+##### **isNotEmpty()**
+
+This method returns `true` if the container field element contains a non-empty string.
+
+##### **hideItem()**
+
+This method hides a container on the Web-form.
+
+##### **showItem()**
+
+This method shows a container on the Web-form.
+
+##### **attachTo(target)**
+
+This method attaches a container to a parent HTML-element given by a `target` parameter. If succeed `true` returned.
+
+#### class methods (*static*)
+
+##### **create(name\[, options])**
+
+This method creates an instance of the class. If failed `null` returned.
+
+The `name` parameter represents an ID of the created container.
+
+For details of `options` parameter see a `createElement` method description.
+
+##### **createElement(name\[, options\[, bRetChild]])**
+
+This method creates a container with all elements needed for input field component to function.
+
+The `name` parameter represents an ID of the created container.
+
+The `options` structure has listed below:
+
+|option name|value type|default value|description|
+|:---|---|---:|:---|
+|`host`|`HTMLElement`|---|an HTML-element which is a host for all container elements|
+|`idPref`|`string`|---|a prefix which modified a container ID, if given|
+|`label`|`string`|---|a text for the field label|
+|`labelPosition`|`string`|---|defines a position to place a label|
+|`useDelim`|`boolean`|`true`|defines whether a delimeter is used within a text of a label|
+|`baseClassID`|`object`|---|containes a list of class name attributes for container elements|
+|`hint`|`string`|---|defines a helper string which is shown when a field content is empty|
+|`fldType`|`string`|---|defines a field type|
+|`isReadOnly`|`boolean`|`true`|defines whether a field content can be modified|
+
+The `baseClassID` structure has listed below:
+
+|option name|value type|default value|description|
+|:---|---|---:|:---|
+|`main`|---|---|containes a list of class name attributes for all elements|
+|`host`|---|---|containes a list of class name attributes for container host|
+|`label`|---|---|containes a list of class name attributes for label element|
+|`field`|---|---|containes a list of class name attributes for field element|
+
+The `bRetChild` parameter, if given, changes the result value of the method. It must be of a `boolean` type. If value is `false` the only host element is returned as a result (a default behavoir). If `true`, an `object` of the following structure is returned:
+
+|property name|value type|description|
+|:---|---|:---|
+|`host`|`HTMLElement`|a container host element|
+|`label`|`HTMLElement`|a container label element|
+|`field`|`HTMLElement`|a container field element|
+
+#### class methods (*special*)
+
+##### **on(name, event)**
+
+This method sets event handler addressed by `name` parameter for the class instance.
+
+> 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|
+|:---|:---|
+|`value-changed`|fired when value is changed|
+|`value-empty`|fired due editing of the field when its value become an empty string|

package/doc/html-ctrls-list.md

@@ -1,6 +1,6 @@
->|***rev.*:**|0.1.11|
+>|***rev.*:**|0.1.15|
 >|:---|---:|
->|date:|2022-09-25|
+>|date:|2023-07-04|
 
 ## Introduction
 
@@ -27,6 +27,7 @@ The `options` structure has listed below:
 |:---|---|---:|:---|
 |`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|
 
 #### class properties
 
@@ -112,6 +113,8 @@ This method adds a given item to a container members and if succeed returns its
 
 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])**
 
 This method deletes an item addressed by the given `index` from a container members and if succeed `true` is returned.
@@ -161,8 +164,9 @@ 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|
-|`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|
+|`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*>|
@@ -405,7 +409,7 @@ 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`|*will deprecate (use `useClear` instead)*|
+|`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.4|
+>|***rev.*:**|0.1.8|
 >|:---|---:|
->|date:|2022-09-22|
+>|date:|2023-06-12|
 
 ## Introduction
 
@@ -74,6 +74,14 @@ This function applies the class attribute defined by `CSS_CLASS_CURRENT` for a g
 
 This function removes the class attribute defined by `CSS_CLASS_CURRENT` for a given HTML-element. If succeed `true` is returned.
 
+#### **unlockHtmlElement(object)**
+
+This function enables a given HTML-element.
+
+#### **lockHtmlElement(args)**
+
+This function disables a given HTML-element.
+
 #### **activateHtmlElements(args)**
 
 This function enables all HTML-elements listed by `args`.
@@ -94,24 +102,25 @@ The `options` parameter if sets to `true` force the function to remove all dupli
 
 > 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)**
+#### **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.|
+|`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.|
+|`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|
+|`data`|---|`undefined`|defines a data-attributes of an element|
 
 If succeed, the function returned `HTMLElement` and `null` if failed.
 
@@ -120,3 +129,7 @@ This function make all the jobs under the hood. So there is no need to call DOM-
 #### **valueToIDString(value)**
 
 This function tries to convert a given `value` to `ID_STRING`. 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,12 +1,13 @@
-// [v0.1.010-20220922]
+// [v0.1.018-20230629]
 
 // === 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 = require('./lib/html-ctrls/list.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-btns.js');
+const html_list_btn = require('./lib/html-ctrls/lists-btn.js');
 
 // === module extra block (helper functions) ===
 
@@ -28,6 +29,8 @@ 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;
@@ -40,17 +43,25 @@ exports.THtmlButtonsSet = html_bts.THtmlButtonsSet;
 exports.THtmlButtonsControllerARCSet = html_bts.THtmlButtonsControllerARCSet;
 exports.BTS_DEF_GROUP_NAME = html_bts.BTS_DEF_GROUP_NAME;
 
+// experimental
+exports.THtmlInputField = html_flds.THtmlInputField;
+
 exports.THtmlListButtonsController = html_list_btn.THtmlListButtonsController;
 
 // experimental
 exports.valueToIDString = html_helper.valueToIDString;
+exports.readAsAttrValue = html_helper.readAsAttrValue;
 exports.createNewHtmlElement = html_helper.createNewHtmlElement;
 
-exports.classes = {
+exports.component = {
   THtmlStubItemsSet: exports.THtmlStubItemsSet,
   THtmlItemsListContainer: exports.THtmlItemsListContainer,
   THtmlItemsListController: exports.THtmlItemsListController,
   THtmlButtonsSet: exports.THtmlButtonsSet,
   THtmlListButtonsController: exports.THtmlListButtonsController,
   THtmlButtonsControllerARCSet: exports.THtmlButtonsControllerARCSet,
+  // experimental
+  THtmlInputField: exports.THtmlInputField,
 };
+// will deprecate
+exports.classes = exports.component;