@cntwg/html-helper 0.0.25 → 0.0.27

package/lib/html-helper-lib.js

@@ -1,14 +1,17 @@
-// [v0.1.039-20250329]
+// [v0.1.043-20250827]
 
 // === module init block ===
 
 const {
-  readAsString,
   isArray, isObject, isPlainObject, valueToArray,
   valueToIDString,
 } = require('@ygracs/bsfoc-lib-js');
 
-// === module extra block (helper functions) ===
+// === module inner block ===
+
+const etlHTagInputForBtn = new Set([
+  'button', 'submit', 'reset', 'image',
+]);
 
 // === module main block ===
 
@@ -27,65 +30,89 @@ const CSS_CLASS_HIDDEN = 'hidden';
  */
 
 /**
+ * Checks if the given object is an instance of an `HTMLElement`.
  * @function isHTMLElement
  * @param {any} obj - some element
  * @return {boolean}
- * @description Checks if the given object is an instance of an `HTMLElement`.
  */
 function isHTMLElement(obj) {
   return obj instanceof HTMLElement;
 };
 
 /**
+ * Checks if the given object is an HTML-button.
+ * @function isHTMLButton
+ * @param {any} obj - element to be verified
+ * @returns {boolean}
+ */
+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;
+}
+
+/**
+ * Checks if the given object is an instance of a `HTMLElement`
+ * and if so it's marked as "selected".
  * @function isSelectedHTMLElement
  * @param {HTMLElement} obj - some element
  * @return {boolean}
- * @description Checks if the given object is an instance of a `HTMLElement`
- *              and if so it's marked as "selected".
  */
 function isSelectedHTMLElement(obj) {
   return isHTMLElement(obj) && obj.classList.contains(CSS_CLASS_SELECTED);
 };
 
 /**
+ * Checks if the given object is an instance of a `HTMLElement`
+ * and if so it's marked as "current".
  * @function isCurrentHTMLElement
  * @param {HTMLElement} obj - some element
  * @return {boolean}
- * @description Checks if the given object is an instance of a `HTMLElement`
- *              and if so it's marked as "current".
  */
 function isCurrentHTMLElement(obj) {
   return isHTMLElement(obj) && obj.classList.contains(CSS_CLASS_CURRENT);
 };
 
 /**
+ * Checks if the given object is an instance of a `HTMLElement`
+ * and if so it's marked as "active".
  * @function isActiveHTMLElement
  * @param {HTMLElement} obj - some element
  * @return {boolean}
- * @description Checks if the given object is an instance of a `HTMLElement`
- *              and if so it's marked as "active".
  */
 function isActiveHTMLElement(obj) {
   return isHTMLElement(obj) && obj.classList.contains(CSS_CLASS_ACTIVE);
 };
 
 /**
+ * Checks if the given object is an instance of a `HTMLElement`
+ * and if so it's marked as "hidden".
  * @function isHiddenHTMLElement
  * @param {HTMLElement} obj - some element
  * @return {boolean}
- * @description Checks if the given object is an instance of a `HTMLElement`
- *              and if so it's marked as "hidden".
  */
 function isHiddenHTMLElement(obj) {
   return isHTMLElement(obj) && obj.classList.contains(CSS_CLASS_HIDDEN);
 };
 
 /**
+ * Hides a given HTML-element.
  * @since v0.0.23
  * @function hideHTMLElement
  * @param {HTMLElement} obj - some element
  * @return {boolean}
- * @description Hides a given HTML-element.
  */
 function hideHTMLElement(obj) {
   const isSUCCEED = isHTMLElement(obj);
@@ -94,11 +121,11 @@ function hideHTMLElement(obj) {
 };
 
 /**
+ * Shows a given HTML-element.
  * @since v0.0.23
  * @function showHTMLElement
  * @param {HTMLElement} obj - some element
  * @return {boolean}
- * @description Shows a given HTML-element.
  */
 function showHTMLElement(obj) {
   const isSUCCEED = isHTMLElement(obj);
@@ -107,11 +134,11 @@ function showHTMLElement(obj) {
 };
 
 /**
+ * Makes selected a given HTML-element.
  * @since v0.0.23
  * @function selectHTMLElement
  * @param {HTMLElement} obj - some element
  * @return {boolean}
- * @description Makes selected a given HTML-element.
  */
 function selectHTMLElement(obj) {
   const isSUCCEED = isHTMLElement(obj);
@@ -120,11 +147,11 @@ function selectHTMLElement(obj) {
 };
 
 /**
+ * Makes unselected a given HTML-element.
  * @since v0.0.23
  * @function unselectHTMLElement
  * @param {HTMLElement} obj - some element
  * @return {boolean}
- * @description Makes unselected a given HTML-element.
  */
 function unselectHTMLElement(obj) {
   const isSUCCEED = isHTMLElement(obj);
@@ -133,11 +160,11 @@ function unselectHTMLElement(obj) {
 };
 
 /**
+ * Marks a given HTML-element as "current".
  * @since v0.0.23
  * @function markHTMLElementAsCurrent
  * @param {HTMLElement} obj - some element
  * @return {boolean} - `true` if succeed.
- * @description Marks a given HTML-element as "current".
  */
 function markHTMLElementAsCurrent(obj) {
   const isSUCCEED = isHTMLElement(obj);
@@ -146,11 +173,11 @@ function markHTMLElementAsCurrent(obj) {
 };
 
 /**
+ * Unmarks a given HTML-element previous marked as "current".
  * @since v0.0.23
  * @function unmarkCurrentHTMLElement
  * @param {HTMLElement} obj - some element
  * @return {boolean}
- * @description Unmarks a given HTML-element previous marked as "current".
  */
 function unmarkCurrentHTMLElement(obj) {
   const isSUCCEED = isHTMLElement(obj);
@@ -159,11 +186,11 @@ function unmarkCurrentHTMLElement(obj) {
 };
 
 /**
+ * Marks a given HTML-element as "active".
  * @since v0.0.23
  * @function markHTMLElementAsActive
  * @param {HTMLElement} obj - some element
  * @return {boolean}
- * @description Marks a given HTML-element as "active".
  */
 function markHTMLElementAsActive(obj) {
   const isSUCCEED = isHTMLElement(obj);
@@ -172,11 +199,11 @@ function markHTMLElementAsActive(obj) {
 };
 
 /**
+ * Unmarks a given HTML-element previous marked as "active".
  * @since v0.0.23
  * @function unmarkActiveHTMLElement
  * @param {HTMLElement} obj - some element
  * @return {boolean}
- * @description Unmarks a given HTML-element previous marked as "active".
  */
 function unmarkActiveHTMLElement(obj) {
   const isSUCCEED = isHTMLElement(obj);
@@ -185,11 +212,11 @@ function unmarkActiveHTMLElement(obj) {
 };
 
 /**
+ * Disables a given HTML-element.
  * @since v0.0.23
  * @function lockHTMLElement
  * @param {HTMLElement} obj - some element
  * @return {boolean}
- * @description Disables a given HTML-element.
  */
 function lockHTMLElement(obj) {
   let isSUCCEED = isHTMLElement(obj);
@@ -202,20 +229,18 @@ function lockHTMLElement(obj) {
         obj.disabled = true;
         break;
       }
-      default: {
-        break;
-      }
+      default: {}
     };
   };
   return isSUCCEED;
 };
 
 /**
+ * Enables a given HTML-element.
  * @since v0.0.23
  * @function unlockHTMLElement
  * @param {HTMLElement} obj - some element
  * @return {boolean}
- * @description Enables a given HTML-element.
  */
 function unlockHTMLElement(obj) {
   let isSUCCEED = isHTMLElement(obj);
@@ -235,11 +260,11 @@ function unlockHTMLElement(obj) {
 };
 
 /**
+ * Enables an HTML-elements given by a list of a function params.
  * @since v0.0.23
  * @function activateHTMLElements
  * @param {...HTMLElement} obj - some element
  * @return {void}
- * @description Enables an HTML-elements given by a list of a function params.
  */
 function activateHTMLElements(...args) {
   for (let item of args) {
@@ -248,11 +273,11 @@ function activateHTMLElements(...args) {
 };
 
 /**
+ * Disables an HTML-elements given by a list of a function params.
  * @since v0.0.23
  * @function inactivateHTMLElements
  * @param {...HTMLElement} obj - some element
  * @return {void}
- * @description Disables an HTML-elements given by a list of a function params.
  */
 function inactivateHTMLElements(...args) {
   for (let item of args) {
@@ -261,11 +286,11 @@ function inactivateHTMLElements(...args) {
 };
 
 /**
+ * Tries to convert a given value to a valid name of an HTML-tag.
  * @since v0.0.21
  * @function readAsTagName
  * @param {any} value - some value
  * @return {string}
- * @description Tries to convert a given value to a valid name of an HTML-tag.
  */
 function readAsTagName(value) {
   let tagName = valueToIDString(value, { ignoreNumbers: true });
@@ -284,12 +309,11 @@ function readAsTagName(value) {
 };
 
 /**
+ * Tries to convert a given value to a valid name of an HTML-attribute.
  * @since v0.0.21
  * @function readAsAttrName
  * @param {any} value - some value
  * @return {string}
- * @description Tries to convert a given value to a valid name
- *              of an HTML-attribute.
  */
 function readAsAttrName(value) {
   let attrName = valueToIDString(value, { ignoreNumbers: true });
@@ -307,11 +331,11 @@ function readAsAttrName(value) {
 };
 
 /**
+ * Tries to convert a given value to a valid "attribute value".
  * @since v0.0.18
  * @function readAsAttrValue
  * @param {any} value - some value
  * @return {?string}
- * @description Tries to convert a given value to a valid "attribute value".
  */
 function readAsAttrValue(value) {
   let result = null;
@@ -335,13 +359,12 @@ function readAsAttrValue(value) {
 };
 
 /**
+ * Tries to convert a given value to a list of a valid "class attributes".
  * @since v0.0.13
  * @function valueToClassList
  * @param {any} value - some value
  * @param {boolean} [opt] - flag that indicates whether a dups allowed
  * @return {string[]}
- * @description Tries to convert a given value to a list of a valid
- *              "class attributes".
  */
 function valueToClassList(value, opt) {
   let result = [];
@@ -363,12 +386,12 @@ function valueToClassList(value, opt) {
 };
 
 /**
+ * Tries to convert a given value to a valid identifier suitable as a value
+ * for an "ID-attribute" of an HTML-element.
  * @since v0.0.22
  * @function valueToElementID
  * @param {any} value - some value
  * @return {string}
- * @description Tries to convert a given value to a valid identifier
- *              suitable as a value for an "ID-attribute" of an HTML-element.
  */
 function valueToElementID(value) {
   let id = valueToIDString(value);
@@ -386,22 +409,22 @@ function valueToElementID(value) {
 };
 
 /**
+ * An element descriptor.
  * @typedef {Object} elemDesc
  * @property {string} [id] - element ID
  * @property {string} [text] - some text
- * @property {object} [attr] - an attributes list
+ * @property {Object<string, any>} [attr] - an attributes list
  * @property {string|string[]} [classNames] - a class names list (added since v0.0.19)
- * @property {object} [data] - a 'dataset'-attributes list
- * @description An element description.
+ * @property {Object<string, any>} [data] - a 'dataset'-attributes list
  */
 
 /**
+ * Creates a new HTML-element.
  * @since 0.0.25
  * @function createNewHTMLElement
  * @param {string} tagName - an element tag name
- * @param {elemDesc} [opt] - an element description object
+ * @param {elemDesc} [opt] - an element descriptor object
  * @return {?HTMLElement}
- * @description Creates a new HTML-element.
  */
 function createNewHTMLElement(tagName, opt) {
   let item = null;
@@ -495,6 +518,7 @@ module.exports.CSS_CLASS_STRING = /*function(){ return*/ {
 }/*}*/;
 
 module.exports.isHTMLElement = isHTMLElement;
+module.exports.isHTMLButton = isHTMLButton;
 module.exports.isCurrentHTMLElement = isCurrentHTMLElement;
 module.exports.isSelectedHTMLElement = isSelectedHTMLElement;
 module.exports.isActiveHTMLElement = isActiveHTMLElement;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cntwg/html-helper",
-  "version": "0.0.25",
+  "version": "0.0.27",
   "description": "A base HTML-helper library for js",
   "author": "ygracs <cs70th-om@rambler.ru>",
   "license": "MIT",
@@ -32,18 +32,8 @@
     "test-bs": "jest base/",
     "test-bs:g1": "jest base/fg-1",
     "test-bs:g2": "jest base/fg-2",
-    "test-lc1": "jest THtmlItemsListContainer",
-    "test-lc2": "jest THtmlItemsListController",
     "test-lc2:bs": "jest THtmlItemsListController/base",
     "test-lc2:ec": "jest THtmlItemsListController/events",
-    "test-sis": "jest THtmlStubItemsSet",
-    "test-btn": "jest THtmlButtonsSet",
-    "test-lbc": "jest THtmlListButtonsController",
-    "test-lbc:bs": "jest THtmlListButtonsController/base",
-    "test-lbc:ec": "jest THtmlListButtonsController/events",
-    "test-bc1": "jest THtmlButtonsControllerARCSet",
-    "test-bc1:bs": "jest THtmlButtonsControllerARCSet/base",
-    "test-bc1:ec": "jest THtmlButtonsControllerARCSet/events",
     "build-doc-md": "jsdoc2md",
     "build-doc-html": "jsdoc"
   },
@@ -52,13 +42,13 @@
     "#test-dir/*": "./__test__/*"
   },
   "dependencies": {
-    "@ygracs/bsfoc-lib-js": "^0.2.3",
-    "@ygracs/lists-lib-js": "^0.0.4"
+    "@ygracs/bsfoc-lib-js": "^0.3.0",
+    "@ygracs/lists-lib-js": "^0.1.0"
   },
   "devDependencies": {
-    "jest": "^29.7.0",
-    "jest-environment-jsdom": "^29.7.0",
-    "jsdoc-to-markdown": "^9.1.1",
+    "jest": "^30.0.5",
+    "jest-environment-jsdom": "^30.0.5",
+    "jsdoc-to-markdown": "^9.1.2",
     "minimist": "^1.2.8"
   }
 }