@cntwg/html-helper 0.0.26 → 0.1.0

package/lib/html-helper-lib.js

@@ -1,4 +1,4 @@
-// [v0.1.041-20250509]
+// [v0.1.044-20251023]
 
 // === module init block ===
 
@@ -7,7 +7,11 @@ const {
   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 ===
 
@@ -26,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);
@@ -93,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);
@@ -106,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);
@@ -119,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);
@@ -132,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);
@@ -145,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);
@@ -158,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);
@@ -171,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);
@@ -184,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);
@@ -208,11 +236,11 @@ function lockHTMLElement(obj) {
 };
 
 /**
+ * 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);
@@ -232,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) {
@@ -245,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) {
@@ -258,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 });
@@ -281,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 });
@@ -304,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;
@@ -332,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 = [];
@@ -360,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);
@@ -383,22 +409,22 @@ function valueToElementID(value) {
 };
 
 /**
+ * An element descriptor.
  * @typedef {Object} elemDesc
  * @property {string} [id] - element ID
  * @property {string} [text] - some text
  * @property {Object<string, any>} [attr] - an attributes list
  * @property {string|string[]} [classNames] - a class names list (added since v0.0.19)
  * @property {Object<string, any>} [data] - a 'dataset'-attributes list
- * @description An element description.
  */
 
 /**
+ * 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;
@@ -472,11 +498,6 @@ function createNewHTMLElement(tagName, opt) {
   return item;
 };
 
-/** @deprecated */
-function createNewHtmlElement(...args) {
-  return createNewHTMLElement(...args);
-};
-
 /***
  * (* class definitions *)
  */
@@ -492,6 +513,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;
@@ -512,15 +534,12 @@ module.exports.inactivateHTMLElements = inactivateHTMLElements;
 
 module.exports.valueToClassList = valueToClassList;
 
-// experimental
+// * experimental *
 module.exports.createNewHTMLElement = createNewHTMLElement;
 module.exports.readAsAttrValue = readAsAttrValue;
 module.exports.readAsTagName = readAsTagName;
 module.exports.readAsAttrName = readAsAttrName;
 module.exports.valueToElementID = valueToElementID;
 
-// re-exported
+// * re-exported *
 module.exports.valueToIDString = valueToIDString;
-
-// @deprecated
-module.exports.createNewHtmlElement = createNewHtmlElement;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cntwg/html-helper",
-  "version": "0.0.26",
+  "version": "0.1.0",
   "description": "A base HTML-helper library for js",
   "author": "ygracs <cs70th-om@rambler.ru>",
   "license": "MIT",
@@ -10,18 +10,11 @@
   },
   "keywords": [
     "electron",
-    "html",
-    "component"
+    "html"
   ],
   "main": "./index.js",
   "files": [
     "doc/*.md",
-    "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",
     "lib/html-helper-lib.js",
     "lib/event-hfunc.js",
     "index.js",
@@ -32,8 +25,6 @@
     "test-bs": "jest base/",
     "test-bs:g1": "jest base/fg-1",
     "test-bs:g2": "jest base/fg-2",
-    "test-lc2:bs": "jest THtmlItemsListController/base",
-    "test-lc2:ec": "jest THtmlItemsListController/events",
     "build-doc-md": "jsdoc2md",
     "build-doc-html": "jsdoc"
   },
@@ -42,13 +33,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.2.0",
+    "jest-environment-jsdom": "^30.2.0",
+    "jsdoc-to-markdown": "^9.1.2",
     "minimist": "^1.2.8"
   }
 }