@cntwg/html-helper 0.0.18 → 0.0.19

package/CHANGELOG.md

@@ -1,3 +1,14 @@
+#### *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.

package/README.md

@@ -1,6 +1,6 @@
->|***rev.*:**|0.1.3|
+>|***rev.*:**|0.1.4|
 >|:---|---:|
->|date:|2023-04-09|
+>|date:|2023-06-29|
 
 ## Introduction
 
@@ -34,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.14|
+>|***rev.*:**|0.1.15|
 >|:---|---:|
->|date:|2023-04-04|
+>|date:|2023-07-04|
 
 ## Introduction
 
@@ -409,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.5|
+>|***rev.*:**|0.1.8|
 >|:---|---:|
->|date:|2023-03-30|
+>|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.
 

package/index.js

@@ -1,10 +1,11 @@
-// [v0.1.016-20230409]
+// [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/buttons.js');
+const html_flds = require('./lib/html-ctrls/fields.js');
 
 const html_list_btn = require('./lib/html-ctrls/lists-btn.js');
 
@@ -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,6 +43,9 @@ 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
@@ -54,6 +60,8 @@ exports.component = {
   THtmlButtonsSet: exports.THtmlButtonsSet,
   THtmlListButtonsController: exports.THtmlListButtonsController,
   THtmlButtonsControllerARCSet: exports.THtmlButtonsControllerARCSet,
+  // experimental
+  THtmlInputField: exports.THtmlInputField,
 };
 // will deprecate
 exports.classes = exports.component;

package/lib/html-ctrls/buttons.js

@@ -1,28 +1,29 @@
-// [v0.1.047-20230408]
+// [v0.1.049-20230614]
 
 // === module init block ===
 
 const {
-  //readAsString,
-  //readAsNumber,
   isNotEmptyString,
   isPlainObject, valueToArray,
   TItemsICollection,
 } = require('@ygracs/bsfoc-lib-js');
 
 const {
-  isHTMLElement, CSS_CLASS_STRING,
+  isHTMLElement,
   valueToIDString,
+  lockHtmlElement, unlockHtmlElement,
+  CSS_CLASS_STRING,
 } = require('../html-helper-lib.js');
 
 const {
   pushEventHandler, triggerEventHandler,
+  readOnClickEventInfo,
 } = require('./mod-hfunc.js');
 
 const {
-  CSS_CLASS_SELECTED,
+  //CSS_CLASS_SELECTED,
   CSS_CLASS_DISABLED,
-  CSS_CLASS_HIDDEN,
+  //CSS_CLASS_HIDDEN,
 } = CSS_CLASS_STRING;
 
 const BTS_DEF_GROUP_NAME = 'all';
@@ -53,32 +54,6 @@ function isHTMLButton(obj){
   return result;
 }
 
-function readOnClickEventInfo(e) {
-  let item = null;
-  //let on_click_num = readAsNumber(e.detail, 0);
-  const { eventPhase, detail: onClickNum } = e;
-  //console.log('CHECK: e => ditail:['+onClickNum+']');
-  //console.log('CHECK: e => phase:['+eventPhase+']');
-  switch (eventPhase) {
-    //*case 1:
-    //* // NOTE: currently on eventPhase = 2 and 3
-    case 2: {
-      /**/// capturing stage
-      item = e.target;
-      break;
-    }
-    case 3: {
-      /**/// bubblig stage
-      item = e.currentTarget;
-      break;
-    }
-    default: {
-      break;
-    }
-  };
-  return { item, onClickNum };
-};
-
 // === module main block (function definitions) ===
 
 // === module main block (class definitions) ===
@@ -137,19 +112,11 @@ class THtmlButtonsSet {
   }
 
   enableItem(name){
-    const item = this.#_btnCol.getItem(name);
-    if (item) {
-      item.classList.remove(CSS_CLASS_DISABLED);
-      item.disabled = false;
-    };
+    unlockHtmlElement(this.#_btnCol.getItem(name));
   }
 
   disableItem(name){
-    const item = this.#_btnCol.getItem(name);
-    if (item) {
-      item.classList.add(CSS_CLASS_DISABLED);
-      item.disabled = true;
-    };
+    lockHtmlElement(this.#_btnCol.getItem(name));
   }
 
   hasGroup(name){
@@ -170,22 +137,12 @@ class THtmlButtonsSet {
 
   enableGroup(value){
     const group = this.#_btnCol.getCategory(value);
-    valueToArray(group).forEach((item) => {
-      if (item) {
-        item.classList.remove(CSS_CLASS_DISABLED);
-        item.disabled = false;
-      };
-    });
+    valueToArray(group).forEach(item => unlockHtmlElement(item));
   }
 
   disableGroup(value){
     const group = this.#_btnCol.getCategory(value);
-    valueToArray(group).forEach((item) => {
-      if (item) {
-        item.classList.add(CSS_CLASS_DISABLED);
-        item.disabled = true;
-      };
-    });
+    valueToArray(group).forEach(item => lockHtmlElement(item));
   }
 
   static get isHTMLButton(){
@@ -210,11 +167,11 @@ class THtmlButtonsControllerARCSet {
     if (!isHTMLButton(btnApply)) btnApply = null;
     if (!isHTMLButton(btnReset)) btnReset = null;
     if (!isHTMLButton(btnCancel)) btnCancel = null;
-    const controls = {
+    /*const controls = {
       btnApply,
       btnReset,
       btnCancel,
-    };
+    };*/ // // TODO:  ???
     // init buttons set
     const _btnSet = new THtmlButtonsSet();
     this.#_btnSet = _btnSet;
@@ -222,23 +179,23 @@ class THtmlButtonsControllerARCSet {
     _btnSet.addGroup('all');
     if (btnApply) {
       _btnSet.addItem('btn_apply', btnApply, 'main', 'all');
-      btnApply.addEventListener('click', this.#_on_btn_apply_pressed);
+      btnApply.addEventListener('click', e => this.#_on_btn_pressed(e, 'apply'));
     };
     if (btnReset) {
       _btnSet.addItem('btn_reset', btnReset, 'main', 'all');
-      btnReset.addEventListener('click', this.#_on_btn_reset_pressed);
+      btnReset.addEventListener('click', e => this.#_on_btn_pressed(e, 'reset'));
     };
     if (btnCancel) {
       _btnSet.addItem('btn_cancel', btnCancel, 'all');
-      btnCancel.addEventListener('click', this.#_on_btn_cancel_pressed);
+      btnCancel.addEventListener('click', e => this.#_on_btn_pressed(e, 'cancel'));
     };
     _btnSet.disableGroup('main');
     // init events controller
     this.#_events = new Map();
   }
 
-  #_on_btn_apply_pressed = (e) => {
-    //console.log('THtmlListButtonsController._on_btn_apply_pressed() ==> was called...');
+  #_on_btn_pressed = (e, key) => {
+    //console.log(`THtmlListButtonsController._on_btn_pressed().key(${key}) ==> was called...`);
     //e.preventDefault(); /* need to reconsider reason for use */
     const { item, onClickNum } = readOnClickEventInfo(e);
     if (
@@ -246,33 +203,7 @@ class THtmlButtonsControllerARCSet {
       && (onClickNum === 0 || onClickNum === 1)
       && !item.classList.contains(CSS_CLASS_DISABLED)
     ) {
-      this.#_triggerEvent('btn-apply-pressed', e);
-    };
-  }
-
-  #_on_btn_reset_pressed = (e) => {
-    //console.log('THtmlListButtonsController._on_btn_reset_pressed() ==> was called...');
-    //e.preventDefault(); /* need to reconsider reason for use */
-    const { item, onClickNum } = readOnClickEventInfo(e);
-    if (
-      item instanceof HTMLElement
-      && (onClickNum === 0 || onClickNum === 1)
-      && !item.classList.contains(CSS_CLASS_DISABLED)
-    ) {
-      this.#_triggerEvent('btn-reset-pressed', e);
-    };
-  }
-
-  #_on_btn_cancel_pressed = (e) => {
-    //console.log('THtmlListButtonsController._on_btn_cancel_pressed() ==> was called...');
-    //e.preventDefault(); /* need to reconsider reason for use */
-    const { item, onClickNum } = readOnClickEventInfo(e);
-    if (
-      item instanceof HTMLElement
-      && (onClickNum === 0 || onClickNum === 1)
-      && !item.classList.contains(CSS_CLASS_DISABLED)
-    ) {
-      this.#_triggerEvent('btn-cancel-pressed', e);
+      this.#_triggerEvent(`btn-${key}-pressed`, e);
     };
   }
 
@@ -309,5 +240,3 @@ exports.THtmlButtonsControllerARCSet = THtmlButtonsControllerARCSet;
 exports.BTS_DEF_GROUP_NAME = BTS_DEF_GROUP_NAME;
 
 exports.isHTMLButton = isHTMLButton;
-
-exports.readOnClickEventInfo = readOnClickEventInfo;

package/lib/html-ctrls/fields.js

@@ -0,0 +1,342 @@
+// [v0.1.011-20230704]
+
+// === module init block ===
+
+const {
+  readAsBool, readAsString,
+  isEmptyString, isNotEmptyString,
+  isPlainObject,
+} = require('@ygracs/bsfoc-lib-js');
+
+const {
+  isHTMLElement, createNewHtmlElement,
+  valueToIDString, valueToClassList,
+  readAsAttrValue,
+  showHtmlElement, hideHtmlElement,
+} = require('../html-helper-lib.js');
+
+const {
+  pushEventHandler, triggerEventHandler,
+} = require('./mod-hfunc.js');
+
+// === module extra block (helper functions) ===
+
+const lpAllowedValues = new Map([
+  [ 'before', 0 ],
+  [ 'after', 1 ],
+  [ 'default', 0 ],
+]);
+
+function getInputFieldTypeDescr(value){
+  let fldType = readAsString(value, '', true);
+  if (fldType === '') fldType = 'default';
+  let fldSubType = '';
+  switch (fldType) {
+    case 'text':
+    case 'checkbox': {
+      break;
+    }
+    case 'switch': {
+      fldType = 'checkbox';
+      fldSubType = 'switch';
+      break;
+    }
+    case 'field':
+    case 'default': {
+      fldType = 'text';
+      break;
+    }
+    default: {
+      fldType = '';
+      break;
+    }
+  };
+  return { type: fldType, subtype: fldSubType };
+};
+
+function getLabelPositionID(value){
+  let key = readAsString(value, '', true);
+  if (!lpAllowedValues.has(key)) key = 'default';
+  return lpAllowedValues.get(key);
+};
+
+// === module main block ===
+
+/***
+ * (* constant definitions *)
+ */
+
+/***
+ * (* function definitions *)
+ */
+
+/***
+ * (* class definitions *)
+ */
+
+class THtmlInputField {
+  #_host = null;
+  #_label = null;
+  #_field = null;
+  #_id = '';
+  #_value = '';
+  #_options = null;
+  #_status = null;
+  #_events = null;
+
+  constructor(name, eholds, opt){
+    // load elements
+    const _eholds = isPlainObject(eholds) ? eholds : {};
+    let { host, label, field } = _eholds;
+    // save elements
+    if (!isHTMLElement(host)) host = null;
+    if (!isHTMLElement(label)) label = null;
+    if (!isHTMLElement(field)) field = null;
+    this.#_host = host;
+    this.#_label = label;
+    this.#_field = field;
+    // load options
+    const _options = isPlainObject(opt) ? opt : {};
+    let {
+      idPref,
+      baseClassID,
+      hint,
+      type: fldType,
+      readonly: isReadOnly,
+    } = _options;
+    let fldSubType = '';
+    ({ type: fldType, subtype: fldSubType } = getInputFieldTypeDescr(fldType));
+    isReadOnly = readAsBool(isReadOnly, true);
+    // save options
+    this.#_options = _options;
+    // save status
+    this.#_status = {
+      fldType,
+      fldSubType,
+      isReadOnly,
+      isModified: false,
+    };
+    // init an event instance controller
+    if (field) {
+      field.addEventListener('change', this.#_saveFieldData);
+      field.addEventListener('input', this.#_switchFieldStatusOnInput);
+      field.addEventListener('blur', this.#_switchFieldStatusOnBlur);
+    };
+    this.#_events = new Map();
+  }
+
+  get isModified(){
+    return this.#_status.isModified;
+  }
+
+  get value(){
+    const field = this.#_field;
+    let result = '';
+    if (field) {
+      const { fldType } = this.#_status;
+      result = fldType === 'checkbox' ?  field.checked : field.value;
+    };
+    return result;
+  }
+
+  set value(value){
+    const field = this.#_field;
+    if (value !== undefined) {
+      const { fldType } = this.#_status;
+      if (fldType === 'checkbox') {
+        field.checked = value;
+        this.#_status.isModified = false;
+      } else {
+        let _value = readAsString(value, '', {
+          boolToString: true,
+          numberToString: true,
+        });
+        field.value = _value;
+        this.#_status.isModified = false;
+        if (_value === '') {
+          this.#_triggerEvent('value-empty', {
+            type: 'value-empty',
+            target: null,
+          });
+        };
+      };
+    };
+  }
+
+  #_triggerEvent = (name, ...args) => {
+    triggerEventHandler(this.#_events, name, ...args);
+  };
+
+  #_saveFieldData = (e) => {
+    e.preventDefault();
+    const target = e.target;
+    //***/console.log(':'+e.type+':'+target.getAttribute('id')+':\n:saveFieldData() => received OnChange-event');
+    // // TODO:
+    this.#_triggerEvent('value-changed', {
+      type: 'value-changed',
+      target,
+    });
+  };
+
+  #_switchFieldStatusOnInput = (e) => {
+    e.preventDefault();
+    const target = e.target;
+    //***/console.log(':'+e.type+':'+target.getAttribute('id')+':\n:switchFieldStatusOnInput() => received OnInput-event');
+    this.#_status.isModified = true;
+    // // TODO:
+    if (target.value === '') {
+      this.#_triggerEvent('value-empty', {
+        type: 'value-empty',
+        target,
+      });
+    };
+  };
+
+  #_switchFieldStatusOnBlur = (e) => {
+    e.preventDefault();
+    //***/console.log(':'+e.type+':'+e.target.getAttribute('id')+':\n:switchFieldStatusOnBlur() => received OnBlur-event');
+    // // TODO:
+  };
+
+  attachTo(target){
+    const host = this.#_host;
+    let result = false;
+    if (
+      isHTMLElement(target)
+      && isHTMLElement(host)
+    ) {
+      target.append(host);
+      result = true;
+    };
+    return result;
+  }
+
+  isEmpty(){
+    return isEmptyString(this.value);
+  }
+
+  isNotEmpty(){
+    return isNotEmptyString(this.value);
+  }
+
+  show(){
+    showHtmlElement(this.#_host);
+  }
+
+  hide(){
+    hideHtmlElement(this.#_host);
+  }
+
+  clear(){
+    // // TODO:
+  }
+
+  static create(name, opt){
+    const eholds = THtmlInputField.createElement(name, opt, true);
+    const { field } = eholds;
+    return (
+      isHTMLElement(field)
+      ? new THtmlInputField(name, eholds, opt)
+      : null
+    );
+  }
+
+  static createElement(name, opt, doRetChild){
+    const id = valueToIDString(name);
+    const _options = isPlainObject(opt) ? opt : {};
+    let fldSubType = '';
+    let {
+      host,
+      idPref,
+      label,
+      labelPosition,
+      useDelim,
+      baseClassID,
+      hint,
+      type: fldType,
+      readonly: isReadOnly,
+    } = _options;
+    if (!isPlainObject(baseClassID)) baseClassID = {};
+    let {
+      main: bcidMain,
+      host: bcidHost,
+      label: bcidLabel,
+      field: bcidField,
+    } = baseClassID;
+    bcidMain = valueToClassList(bcidMain);
+    bcidHost = valueToClassList(bcidHost);
+    bcidLabel = valueToClassList(bcidLabel);
+    bcidField = valueToClassList(bcidField);
+    idPref = valueToIDString(idPref);
+    hint = readAsString(hint, '', true);
+    ({ type: fldType, subtype: fldSubType } = getInputFieldTypeDescr(fldType));
+    if (fldSubType === 'switch') bcidField.push('switch');
+    labelPosition = getLabelPositionID(labelPosition);
+    if (typeof useDelim !== 'boolean') useDelim = true;
+    label = readAsString(label, '', true);
+    if (label !== '') label = `${label}${useDelim ? ':' : ''}`;
+    isReadOnly = readAsBool(isReadOnly, true);
+    let fldID = idPref === '' ? id : `${idPref}-${id}`;
+    if (!isHTMLElement(host)) {
+      host = createNewHtmlElement('div', {
+        class: bcidHost,
+      });
+    };
+    let lblHolder = null;
+    let fldHolder = null;
+    let items = [];
+    if (host) {
+      lblHolder = host.querySelector(`label[for="${fldID}"]`);
+      if (!lblHolder) {
+        lblHolder = createNewHtmlElement('label', {
+          text: label,
+          attr: {
+            for: fldID,
+          },
+          class: bcidLabel,
+        });
+      };
+      fldHolder = host.querySelector(`input#${fldID}`);
+      if (!fldHolder) {
+        fldHolder = createNewHtmlElement('input', {
+          id: fldID,
+          attr: {
+            type: fldType,
+            placeholder: hint,
+          },
+          class: bcidField,
+        });
+      };
+      if (fldHolder) {
+        if (isReadOnly) {
+          const attr = fldType === 'checkbox' ? 'disabled' : 'readOnly';
+          fldHolder[attr] = true;
+        };
+        if (lblHolder) items.push(lblHolder);
+        items.push(fldHolder);
+      };
+      const len = items.length;
+      if (len > 0) {
+        if (len === 2 && labelPosition === 1) {
+          items = [ items[1], items[0] ];
+        };
+        host.append(...items);
+      };
+    };
+    // // TODO:
+    return (
+      readAsBool(doRetChild, false)
+      ? { host, label: lblHolder, field: fldHolder }
+      : host
+    );
+  }
+
+  on(name, evnt){
+    pushEventHandler(this.#_events, name, evnt);
+  }
+
+};
+
+// === module exports block ===
+
+module.exports.THtmlInputField = THtmlInputField;

package/lib/html-ctrls/lists-btn.js

@@ -1,35 +1,30 @@
-// [v0.1.045-20230408]
+// [v0.1.047-20230614]
 
 // === module init block ===
 
 const {
-  //readAsString,
-  readAsNumber,
-  //isNotEmptyString,
   isPlainObject,
-  //valueToArray,
-  //TItemsICollection,
 } = require('@ygracs/bsfoc-lib-js');
 
 const {
-  CSS_CLASS_STRING,
   isHTMLElement,
+  CSS_CLASS_STRING,
 } = require('../html-helper-lib.js');
 
 const {
   isHTMLButton,
   THtmlButtonsSet,
-  readOnClickEventInfo,
 }  = require('./buttons.js');
 
 const {
   pushEventHandler, triggerEventHandler,
+  readOnClickEventInfo,
 } = require('./mod-hfunc.js');
 
 const {
-  CSS_CLASS_SELECTED,
+  //CSS_CLASS_SELECTED,
   CSS_CLASS_DISABLED,
-  CSS_CLASS_HIDDEN,
+  //CSS_CLASS_HIDDEN,
 } = CSS_CLASS_STRING;
 
 const BTS_DEF_GROUP_NAME = 'all';
@@ -66,12 +61,12 @@ class THtmlListButtonsController {
     if (!isHTMLButton(btnPrev)) btnPrev = null;
     if (!isHTMLButton(btnNext)) btnNext = null;
     if (!isHTMLButton(btnLast)) btnLast = null;
-    const controls = {
+    /*const controls = {
       btnFirst,
       btnPrev,
       btnNext,
       btnLast,
-    };
+    };*/ // // TODO: ???
     // init buttons set
     const _btnSet = new THtmlButtonsSet();
     this.#_btnSet = _btnSet;
@@ -81,8 +76,8 @@ class THtmlListButtonsController {
     if (btnFirst && btnLast) {
       _btnSet.addItem('btn_frst', btnFirst, 'move_bkwd');
       _btnSet.addItem('btn_last', btnLast, 'move_frwd');
-      btnFirst.addEventListener('click', this.#_on_btn_frst_pressed);
-      btnLast.addEventListener('click', this.#_on_btn_last_pressed);
+      btnFirst.addEventListener('click', e => this.#_on_btn_pressed(e, 'first'));
+      btnLast.addEventListener('click', e => this.#_on_btn_pressed(e, 'last'));
     } else {
       _btnSet.addItem('btn_frst', btnFirst, 'dsbl_ctrls');
       _btnSet.addItem('btn_last', btnLast, 'dsbl_ctrls');
@@ -90,8 +85,8 @@ class THtmlListButtonsController {
     if (btnPrev && btnNext) {
       _btnSet.addItem('btn_prev', btnPrev, 'move_bkwd');
       _btnSet.addItem('btn_next', btnNext, 'move_frwd');
-      btnPrev.addEventListener('click', this.#_on_btn_prev_pressed);
-      btnNext.addEventListener('click', this.#_on_btn_next_pressed);
+      btnPrev.addEventListener('click', e => this.#_on_btn_pressed(e, 'prev'));
+      btnNext.addEventListener('click', e => this.#_on_btn_pressed(e, 'next'));
     } else {
       _btnSet.addItem('btn_prev', btnPrev, 'dsbl_ctrls');
       _btnSet.addItem('btn_next', btnNext, 'dsbl_ctrls');
@@ -103,47 +98,8 @@ class THtmlListButtonsController {
     this.#_events = new Map();
   }
 
-  #_on_btn_frst_pressed = (e) => {
-    //console.log('THtmlListButtonsController._on_btn_frst_pressed() ==> was called...');
-    //e.preventDefault(); /* need to reconsider reason for use */
-    const { item, onClickNum } = readOnClickEventInfo(e);
-    if (
-      item instanceof HTMLElement
-      && (onClickNum === 0 || onClickNum === 1)
-      && !item.classList.contains(CSS_CLASS_DISABLED)
-    ) {
-      this.#_triggerEvent('btn-first-pressed', e);
-    };
-  }
-
-  #_on_btn_last_pressed = (e) => {
-    //console.log('THtmlListButtonsController._on_btn_last_pressed() ==> was called...');
-    //e.preventDefault(); /* need to reconsider reason for use */
-    const { item, onClickNum } = readOnClickEventInfo(e);
-    if (
-      item instanceof HTMLElement
-      && (onClickNum === 0 || onClickNum === 1)
-      && !item.classList.contains(CSS_CLASS_DISABLED)
-    ) {
-      this.#_triggerEvent('btn-last-pressed', e);
-    };
-  }
-
-  #_on_btn_prev_pressed = (e) => {
-    //console.log('THtmlListButtonsController._on_btn_prev_pressed() ==> was called...');
-    //e.preventDefault(); /* need to reconsider reason for use */
-    const { item, onClickNum } = readOnClickEventInfo(e);
-    if (
-      item instanceof HTMLElement
-      && (onClickNum === 0 || onClickNum === 1)
-      && !item.classList.contains(CSS_CLASS_DISABLED)
-    ) {
-      this.#_triggerEvent('btn-prev-pressed', e);
-    };
-  }
-
-  #_on_btn_next_pressed = (e) => {
-    //console.log('THtmlListButtonsController._on_btn_next_pressed() ==> was called...');
+  #_on_btn_pressed = (e, key) => {
+    //console.log(`THtmlListButtonsController._on_btn_pressed().key(${key}) ==> was called...`);
     //e.preventDefault(); /* need to reconsider reason for use */
     const { item, onClickNum } = readOnClickEventInfo(e);
     if (
@@ -151,7 +107,7 @@ class THtmlListButtonsController {
       && (onClickNum === 0 || onClickNum === 1)
       && !item.classList.contains(CSS_CLASS_DISABLED)
     ) {
-      this.#_triggerEvent('btn-next-pressed', e);
+      this.#_triggerEvent(`btn-${key}-pressed`, e);
     };
   }
 

package/lib/html-ctrls/mod-hfunc.js

@@ -1,4 +1,4 @@
-// [v0.1.059-20230408]
+// [v0.1.060-20230614]
 
 // === module init block ===
 
@@ -25,9 +25,36 @@ function triggerEventHandler(pool, name, ...args){
     if (pool.has(_name)) pool.get(_name)(...args);
   };
 };
+
+function readOnClickEventInfo(e) {
+  let item = null;
+  const { eventPhase, detail: onClickNum } = e;
+  //console.log('CHECK: e => ditail:['+onClickNum+']');
+  //console.log('CHECK: e => phase:['+eventPhase+']');
+  switch (eventPhase) {
+    //*case 1:
+    //* // NOTE: currently on eventPhase = 2 and 3
+    case 2: {
+      /**/// capturing stage
+      item = e.target;
+      break;
+    }
+    case 3: {
+      /**/// bubblig stage
+      item = e.currentTarget;
+      break;
+    }
+    default: {
+      break;
+    }
+  };
+  return { item, onClickNum };
+};
+
 // === module main block (class definitions) ===
 
 // === module exports block ===
 
 exports.pushEventHandler = pushEventHandler;
 exports.triggerEventHandler = triggerEventHandler;
+exports.readOnClickEventInfo = readOnClickEventInfo;

package/lib/html-helper-lib.js

@@ -1,4 +1,4 @@
-// [v0.1.016-20230330]
+// [v0.1.019-20230614]
 
 // === module init block ===
 
@@ -85,39 +85,53 @@ function unmarkActiveHtmlElement(obj){
   return isSUCCEED;
 };
 
+function lockHtmlElement(obj){
+  let isSUCCEED = isHTMLElement(obj);
+  if (isSUCCEED) {
+    const { classList, tagName } = obj;
+    classList.add(CSS_CLASS_DISABLED);
+    switch (tagName.toLowerCase()) {
+      case 'button':
+      case 'input': {
+        obj.disabled = true;
+        break;
+      }
+      default: {
+        break;
+      }
+    };
+  };
+  return isSUCCEED;
+};
+
+function unlockHtmlElement(obj){
+  let isSUCCEED = isHTMLElement(obj);
+  if (isSUCCEED) {
+    const { classList, tagName } = obj;
+    classList.remove(CSS_CLASS_DISABLED);
+    switch (tagName.toLowerCase()) {
+      case 'button':
+      case 'input': {
+        obj.disabled = false;
+        break;
+      }
+      default: {
+        break;
+      }
+    };
+  };
+  return isSUCCEED;
+};
+
 function inactivateHtmlElements(...args) {
   for (let item of args) {
-    if (isHTMLElement(item)) {
-      item.classList.add(CSS_CLASS_DISABLED);
-      switch (item.tagName.toLowerCase()) {
-        case 'button':
-        case 'input': {
-          item.disabled = true;
-          break;
-        }
-        default: {
-          break;
-        }
-      };
-    };
+    lockHtmlElement(item);
   };
 };
 
 function activateHtmlElements(...args) {
   for (let item of args) {
-    if (isHTMLElement(item)) {
-      item.classList.remove(CSS_CLASS_DISABLED);
-      switch (item.tagName.toLowerCase()) {
-        case 'button':
-        case 'input': {
-          item.disabled = false;
-          break;
-        }
-        default: {
-          break;
-        }
-      };
-    };
+    unlockHtmlElement(item);
   };
 };
 
@@ -192,6 +206,7 @@ function createNewHtmlElement(tagName, opt){
       id,
       text,
       attr,
+      classNames,
       class: _class,
       data: dset,
     } = opt;
@@ -217,6 +232,7 @@ function createNewHtmlElement(tagName, opt){
       };
     };
     // set a class-attributes of the element
+    if (_class === undefined) _class = classNames;
     if (_class !== undefined) {
       const cl = valueToClassList(_class, true);
       if (cl.length > 0) item.classList.add(...cl);
@@ -267,6 +283,8 @@ exports.markHtmlElementAsCurrent = markHtmlElementAsCurrent;
 exports.unmarkCurrentHtmlElement = unmarkCurrentHtmlElement;
 exports.markHtmlElementAsActive = markHtmlElementAsActive;
 exports.unmarkActiveHtmlElement = unmarkActiveHtmlElement;
+exports.lockHtmlElement = lockHtmlElement;
+exports.unlockHtmlElement = unlockHtmlElement;
 exports.activateHtmlElements = activateHtmlElements;
 exports.inactivateHtmlElements = inactivateHtmlElements;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cntwg/html-helper",
-  "version": "0.0.18",
+  "version": "0.0.19",
   "description": "A base HTML-helper library for js",
   "author": "ygracs <cs70th-om@rambler.ru>",
   "license": "MIT",
@@ -13,11 +13,13 @@
     "doc/html-helper-lib.md",
     "doc/html-ctrls-list.md",
     "doc/html-ctrls-btn.md",
+    "doc/html-ctrls-fields.md",
     "lib/html-helper-lib.js",
     "lib/html-ctrls/lists-stubs.js",
     "lib/html-ctrls/lists-btn.js",
     "lib/html-ctrls/list.js",
     "lib/html-ctrls/buttons.js",
+    "lib/html-ctrls/fields.js",
     "lib/html-ctrls/mod-hfunc.js",
     "index.js",
     "CHANGELOG.md"
@@ -40,11 +42,15 @@
     "test-bc1:bs": "jest THtmlButtonsControllerARCSet/base",
     "test-bc1:ec": "jest THtmlButtonsControllerARCSet/events"
   },
+  "imports": {
+    "#lib/*": "./lib/*"
+  },
   "dependencies": {
-    "@ygracs/bsfoc-lib-js": "^0.1.2"
+    "@ygracs/bsfoc-lib-js": "^0.1.3"
   },
   "devDependencies": {
-    "jest": "^29.0.3",
-    "jest-environment-jsdom": "^29.0.3"
+    "jest": "^29.5.0",
+    "jest-environment-jsdom": "^29.5.0",
+    "minimist": "^1.2.8"
   }
 }