@cntwg/html-helper 0.0.26 → 0.0.27

package/CHANGELOG.md

@@ -1,3 +1,12 @@
+#### *v0.0.27*
+
+Pre-release version.
+
+> - `html-helper-lib.md` updated;
+> - `html-ctrls-btn.md` updated;
+> - update dependency on `@ygracs/bsfoc-lib-js` module to v0.3.0;
+> - update dependency on `@ygracs/lists-lib-js` module to v0.1.0.
+
 #### *v0.0.26*
 
 Pre-release version.

package/doc/html-ctrls-btn.md

@@ -1,6 +1,6 @@
->|***rev.*:**|0.1.15|
+>|***rev.*:**|0.1.16|
 >|:---|---:|
->|date:|2024-11-15|
+>|date:|2025-08-27|
 
 ## Introduction
 
@@ -16,15 +16,6 @@ By module, constants that is provided listed in the following table:
 
 ## Module functions
 
-<a name="isHTMLButton"></a>
-#### **isHTMLButton(obj)** => `boolean`
-
-This function checks whether or not a given object represents an HTML-button element and if so returns `true` or `false` if else.
-
-| parameter name | value type | default value | description |
-|:---|---|---:|:---|
-| `obj` | `any` | --- | some element to be checked |
-
 ## Module classes
 
 <a name="THtmlButtonsSet"></a>
@@ -199,6 +190,8 @@ This method inactivates all "button" elements present in a group named by `name`
 |---|---|:---|
 | `function` | yes | contains a default function that verified validity of an element. The function receives element and returns result for validation as a `boolean`. |
 
+> For more details see [`isHTMLButton`](html-helper-lib.md#isHTMLButton).
+
 <a name="THtmlButtonsControllerARCSet"></a>
 ### **THtmlButtonsControllerARCSet**
 

package/doc/html-helper-lib.md

@@ -1,6 +1,6 @@
->|***rev.*:**|0.1.15|
+>|***rev.*:**|0.1.16|
 >|:---|---:|
->|date:|2025-03-29|
+>|date:|2025-08-27|
 
 ## Introduction
 
@@ -33,6 +33,15 @@ This function checks whether or not a given object represents an HTML-element an
 |:---|---|---:|:---|
 | `obj` | `any` | --- | some element to be checked |
 
+<a name="isHTMLButton"></a>
+#### **isHTMLButton(obj)** => `boolean`
+
+This function checks whether or not a given object represents an HTML-button element and if so returns `true` or `false` if else.
+
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `obj` | `any` | --- | some element to be checked |
+
 <a name="isSelectedHTMLElement"></a>
 #### **isSelectedHTMLElement(obj)** => `boolean`
 

package/index.js

@@ -1,4 +1,4 @@
-// [v0.1.028-20250503]
+// [v0.1.029-20250827]
 
 // === module init block ===
 
@@ -71,8 +71,8 @@ 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_helper.isHTMLButton;
 
-module.exports.isHTMLButton = html_bts.isHTMLButton;
 
 module.exports.THtmlInputField = html_flds.THtmlInputField;
 

package/lib/html-ctrls/buttons.js

@@ -1,4 +1,4 @@
-// [v0.1.062-20250509]
+// [v0.1.064-20250827]
 
 // === module init block ===
 
@@ -12,7 +12,7 @@ const {
 } = require('@ygracs/lists-lib-js');
 
 const {
-  isHTMLElement,
+  isHTMLElement, isHTMLButton,
   valueToIDString,
   lockHTMLElement, unlockHTMLElement,
   CSS_CLASS_STRING,
@@ -37,38 +37,10 @@ const {
 
 const BTS_DEF_GROUP_NAME = 'all';
 
-const etlHTagInputForBtn = new Set([
-  'button', 'submit', 'reset', 'image',
-]);
-
 /***
  * (* function definitions *)
  */
 
-/**
- * @function isHTMLButton
- * @param {any} obj - element to be verified
- * @returns {boolean}
- * @description Checks if the given object is an HTML-button.
- */
-function isHTMLButton(obj) {
-  let result = false;
-  if (isHTMLElement(obj)) {
-    switch (obj.tagName.toLowerCase()) {
-      case 'button': {
-        result = true;
-        break;
-      }
-      case 'input': {
-        result = etlHTagInputForBtn.has(obj.type.toLowerCase());
-        break;
-      }
-      default: {}
-    };
-  };
-  return result;
-}
-
 /***
  * (* class definitions *)
  */
@@ -81,7 +53,7 @@ class THtmlButtonsSet {
   #_btnCol;
 
   /**
-   * @description Creates an instance of a buttons set
+   * Creates an instance of a buttons set
    */
   constructor() {
     // define default functions for manipulators
@@ -122,133 +94,133 @@ class THtmlButtonsSet {
   }
 
   /**
+   * Checks whether a target item with a given name exists.
    * @param {string} name - element name
    * @returns {boolean}
    * @see TItemsICollection.hasItem
-   * @description Checks whether a target item with a given name exists.
    */
   hasItem(name) {
     return this.#_btnCol.hasItem(name);
   }
 
   /**
+   * Adds buttons to a set members.
    * @param {string} name - element name
    * @param {any} item - element
    * @param {...string} [group] - name of a target groups
    * @returns {boolean}
    * @see TItemsICollection.addItem
-   * @description Adds buttons to a set members.
    */
   addItem(...args) {
     return this.#_btnCol.addItem(...args);
   }
 
   /**
+   * Adds button to a listed groups.
    * @param {string} name - element name
    * @param {...string} [group] - name of a target groups
    * @returns {boolean}
    * @see TItemsICollection.addItemToCategory
-   * @description Adds button to a listed groups.
    */
   addItemToGroup(...args) {
     return this.#_btnCol.addItemToCategory(...args);
   }
 
   /**
+   * Deletes button from a set members.
    * @param {string} name - element name
    * @returns {boolean}
    * @see TItemsICollection.delItem
-   * @description Deletes button from a set members.
    */
   delItem(name) {
     return this.#_btnCol.delItem(name);
   }
 
   /**
+   * Deletes button from a listed groups.
    * @param {string} name - element name
    * @param {...string} [group] - name of a target groups
    * @returns {boolean}
    * @see TItemsICollection.delItemFromGroup
-   * @description Deletes button from a listed groups.
    */
   delItemFromGroup(...args) {
     return this.#_btnCol.delItemFromGroup(...args);
   }
 
   /**
+   * Renames button in a set.
    * @param {string} name - old name
    * @param {string} value - new name
    * @returns {boolean}
    * @see TItemsICollection.renameItem
-   * @description Renames button in a set.
    */
   renameItem(name, value) {
     return this.#_btnCol.renameItem(name, value, false);
   }
 
   /**
+   * Tries to enable button.
    * @param {string} name - element name
    * @returns {void}
-   * @description Tries to enable button.
    */
   enableItem(name) {
     unlockHTMLElement(this.#_btnCol.getItem(name));
   }
 
   /**
+   * Tries to disable button.
    * @param {string} name - element name
    * @returns {void}
-   * @description Tries to disable button.
    */
   disableItem(name) {
     lockHTMLElement(this.#_btnCol.getItem(name));
   }
 
   /**
+   * Checks whether a target group with a given name exists.
    * @param {string} name - group name
    * @returns {boolean}
    * @see TItemsICollection.hasCategory
-   * @description Checks whether a target group with a given name exists.
    */
   hasGroup(name) {
     return this.#_btnCol.hasCategory(name);
   }
 
   /**
+   * Adds a group with a given name.
    * @param {string} name - group name
    * @returns {boolean}
    * @see TItemsICollection.addCategory
-   * @description Adds a group with a given name.
    */
   addGroup(name) {
     return this.#_btnCol.addCategory(name);
   }
 
   /**
+   * Deletes a group with a given name.
    * @param {string} name - group name
    * @returns {boolean}
    * @see TItemsICollection.delCategory
-   * @description Deletes a group with a given name.
    */
   delGroup(name) {
     return this.#_btnCol.delCategory(name);
   }
 
   /**
+   * Renames group in a set.
    * @param {string} name - old name
    * @param {string} value - new name
    * @returns {boolean}
    * @see TItemsICollection.renameCategory
-   * @description Renames group in a set.
    */
   renameGroup(name, value) {
     return this.#_btnCol.renameCategory(name, value, false);
   }
 
   /**
+   * Enables all buttons in a given group.
    * @param {string} value - group name
    * @returns {void}
-   * @description Enables all buttons in a given group.
    */
   enableGroup(value) {
     const group = this.#_btnCol.getCategory(value);
@@ -256,9 +228,9 @@ class THtmlButtonsSet {
   }
 
   /**
+   * Disables all buttons in a given group.
    * @param {string} value - group name
    * @returns {void}
-   * @description Disables all buttons in a given group.
    */
   disableGroup(value) {
     const group = this.#_btnCol.getCategory(value);
@@ -276,6 +248,14 @@ class THtmlButtonsSet {
 
 };
 
+/**
+ * A description for ARC-buttons set.
+ * @typedef {Object} arcButtonsDesc
+ * @property {?HTMLElement} btnApply - button 'apply'
+ * @property {?HTMLElement} btnReset - button 'reset'
+ * @property {?HTMLElement} btnCancel - button 'cancel'
+ */
+
 /**
  * @classdesc This class implements an interface of a pre-defined buttons set.
  *            A set provide a three button: <apply>, <reset> and <cancel>.
@@ -287,16 +267,8 @@ class THtmlButtonsControllerARCSet {
   #_events;
 
   /**
-   * @typedef {Object} arcButtonsDesc
-   * @property {?HTMLElement} btnApply - button 'apply'
-   * @property {?HTMLElement} btnReset - button 'reset'
-   * @property {?HTMLElement} btnCancel - button 'cancel'
-   * @description A description for ARC-buttons set.
-   */
-
-  /**
+   * Creates an instance of the buttons set.
    * @param {arcButtonsDesc} opt - an option
-   * @description Creates an instance of the buttons set.
    */
   constructor(opt) {
     // load controls
@@ -362,42 +334,42 @@ class THtmlButtonsControllerARCSet {
   }
 
   /**
+   * Disables all buttons in 'main' group.
    * @returns {void}
-   * @description Disables all buttons in 'main' group.
    */
   disableMain() {
     this.#_btnSet.disableGroup('main');
   }
 
   /**
+   * Enables all buttons in 'main' group.
    * @returns {void}
-   * @description Enables all buttons in 'main' group.
    */
   enableMain() {
     this.#_btnSet.enableGroup('main');
   }
 
   /**
+   * Disables all buttons.
    * @returns {void}
-   * @description Disables all buttons.
    */
   disableAll() {
     this.#_btnSet.disableGroup('all');
   }
 
   /**
+   * Enables all buttons.
    * @returns {void}
-   * @description Enables all buttons.
    */
   enableAll() {
     this.#_btnSet.enableGroup('all');
   }
 
   /**
+   * Sets a callback function to handle event.
    * @param {string} name - event name
    * @param {func} evnt - a callback function
    * @returns {void}
-   * @description Sets a callback function to handle event.
    */
   on(name, evnt) {
     pushEventHandler(this.#_events, name, evnt);

package/lib/html-ctrls/fields.js

@@ -1,4 +1,4 @@
-// [v0.1.022-20250509]
+// [v0.1.023-20250827]
 
 // === module init block ===
 
@@ -19,7 +19,7 @@ const {
   pushEventHandler, triggerEventHandler,
 } = require('./mod-hfunc.js');
 
-// === module extra block (helper functions) ===
+// === module inner block ===
 
 const lpAllowedValues = new Map([
   [ 'before', 0 ],
@@ -28,18 +28,18 @@ const lpAllowedValues = new Map([
 ]);
 
 /**
+ * An input field type descriptor
  * @typedef {Object} ifcTypeDesc
  * @property {string} type - field general type
  * @property {string} subtype - field sub-type
- * @description An input field type description
  */
 
 /**
+ * Returns field description by a given type.
  * @function getInputFieldTypeDescr
  * @param {string} value - field type
  * @returns {ifcTypeDesc}
  * @inner
- * @description Returns field description by a given type.
  */
 function getInputFieldTypeDescr(value) {
   let fldType = readAsString(value, { useTrim: true });
@@ -69,11 +69,11 @@ function getInputFieldTypeDescr(value) {
 };
 
 /**
+ * Returns label position ID by its name.
  * @function getLabelPositionID
  * @param {string} value - label position identifier
  * @returns {number}
  * @inner
- * @description Returns label position ID by its name.
  */
 function getLabelPositionID(value) {
   let key = readAsString(value, { useTrim: true });
@@ -96,6 +96,7 @@ function getLabelPositionID(value) {
  */
 
 /**
+ * An options set for create ifc
  * @typedef {Object} OPT_ifcdesc
  * @property {HTMLElement} [host] - host element
  * @property {string} [idPref]
@@ -106,25 +107,24 @@ function getLabelPositionID(value) {
  * @property {string} [hint] - hint to show when empty
  * @property {string} [type] - field type
  * @property {boolean} [readonly] - mode flag
- * @description An options set for create ifc
  */
 
 /**
+ * An options set for `THtmlInputField`-class
  * @typedef {Object} OPT_ifcsett
  * @property {string} [idPref]
  * @property {(string|string[])} [baseClassID]
  * @property {string} [hint] - hint to show when empty
  * @property {string} [type] - field type
  * @property {boolean} [readonly=true] - mode flag
- * @description An options set for `THtmlInputField`-class
  */
 
 /**
+ * A descriptor for an input field elements set.
  * @typedef {Object} ifcElementsDesc
  * @property {HTMLElement} host - host element
  * @property {HTMLElement} label - label element
  * @property {HTMLElement} field - field element
- * @description A description for input field elements set.
  */
 
 /**
@@ -142,13 +142,13 @@ class THtmlInputField {
   /** @type {OPT_ifcsett} */
   #_options = null;
   /**
+   * A controller status
    * @typedef {Object} statIFCtrl
    * @property {string} fldType - field general type
    * @property {string} fldSubType - field sub-type
    * @property {boolean} isReadOnly - mode flag
    * @property {boolean} isModified - indicates whether any changes was made
    * @inner
-   * @description A controller status
    */
   /** @type {statIFCtrl} */
   #_status;// = null;
@@ -156,10 +156,10 @@ class THtmlInputField {
   #_events;// = null;
 
   /**
+   * Creates an instance of an input field element
    * @param {string} name - <*reserved*>
    * @param {ifcElementsDesc} eholds - elements set
    * @param {OPT_ifcsett} [opt] - options
-   * @description Creates an instance of an input field element
    */
   constructor(name, eholds, opt) {
     // load elements
@@ -331,9 +331,9 @@ class THtmlInputField {
   };
 
   /**
+   * Tries to attach an element to a given target.
    * @param {HTMLElement} target - target element
    * @returns {boolean}
-   * @description Tries to attach an element to a given target.
    */
   attachTo(target) {
     const host = this.#_host;
@@ -349,32 +349,32 @@ class THtmlInputField {
   }
 
   /**
+   * Checks if a value of an element is not set.
    * @returns {boolean}
-   * @description Checks if a value of an element is not set.
    */
   isEmpty() {
     return isEmptyString(this.value);
   }
 
   /**
+   * Checks if a value of an element is set.
    * @returns {boolean}
-   * @description Checks if a value of an element is set.
    */
   isNotEmpty() {
     return isNotEmptyString(this.value);
   }
 
   /**
+   * Shows an element.
    * @returns {void}
-   * @description Shows an element.
    */
   show() {
     showHTMLElement(this.#_host);
   }
 
   /**
+   * Hides an element.
    * @returns {void}
-   * @description Hides an element.
    */
   hide() {
     hideHTMLElement(this.#_host);
@@ -382,18 +382,18 @@ class THtmlInputField {
 
   /**
    * @returns {void}
-   * @description not implemented yet.
+   * @todo not implemented yet.
    */
   clear() {
     // // TODO:
   }
 
   /**
+   * Creates a new instance.
    * @param {string} name - <*reserved*>
    * @param {OPT_ifcdesc} opt - options
    * @returns {?THtmlInputField}
    * @static
-   * @description Creates a new instance.
    */
   static create(name, opt) {
     const eholds = THtmlInputField.createElement(name, opt, true);
@@ -406,12 +406,12 @@ class THtmlInputField {
   }
 
   /**
+   * Creates a new elements.
    * @param {string} name
    * @param {OPT_ifcdesc} [opt] - options
    * @param {boolean} [doRetChild=false] - mode flag
    * @returns {(HTMLElement|ifcElementsDesc)}
    * @static
-   * @description Creates a new elements.
    */
   static createElement(name, opt, doRetChild) {
     const id = valueToIDString(name);
@@ -505,10 +505,10 @@ class THtmlInputField {
   }
 
   /**
+   * Sets a callback function to handle event.
    * @param {string} name - event name
    * @param {func} evnt - callback function
    * @returns {void}
-   * @description Sets a callback function to handle event.
    */
   on(name, evnt) {
     pushEventHandler(this.#_events, name, evnt);