@cntwg/html-helper 0.0.26 → 0.0.27

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

@@ -1,4 +1,4 @@
-// [v0.1.049-20250505]
+// [v0.1.050-20250827]
 
 // === module init block ===
 
@@ -27,27 +27,27 @@ const {
  */
 
 /**
+ * A settings to load a stub-elements.
  * @typedef {Object} OPT_ldstubs
  * @property {string} [defaultItem] - <*deprecated*> a default element name
  * @property {boolean} [useClear=true] - to clear before load an elements
  * @property {boolean} [force=false] - run in a force mode
- * @description A settings to load a stub-elements.
  * @todo [since v0.0.26] `defaultItem`-option deprecated
  */
 
 /**
+ * A stub-elements description list.
  * @typedef {Object} OBJ_stubEList
  * @property {Array} items - array of `name`-`element` pairs
  * @property {string} [defaultItem] - a default element name
- * @description A stub-elements description list.
  */
 
 /**
+ * A an options set for a `THtmlStubItemsSet`-class constructor
  * @typedef {Object} OPT_stubconsett
  * @property {(any[])} items - array of `name`-`element` pairs
  * @property {string} [defaultItem] - a default element name
  * @property {boolean} [force=false] - run in a force mode
- * @description A an options set for a `THtmlStubItemsSet`-class constructor
  */
 
 /**
@@ -63,9 +63,9 @@ class THtmlStubItemsSet {
   #_shownItem = null;
 
   /**
+   * Creates an instance of a stub-items set
    * @param {HTMLElement} host - host element
    * @param {(array|OPT_stubconsett|OBJ_stubEList)} [opt] - options
-   * @description Creates an instance of a stub-items set
    * @todo [since v0.0.26] use of an `array`-type as a value of an `opt` is deprecated
    */
   constructor(host, opt) {
@@ -108,8 +108,8 @@ class THtmlStubItemsSet {
   }
 
   /**
+   * Clears an instance content.
    * @returns {void}
-   * @description Clears an instance content.
    */
   clear() {
     // // TODO: check if any item is shown
@@ -119,9 +119,9 @@ class THtmlStubItemsSet {
   }
 
   /**
+   * Sets a default item.
    * @param {string} name - an element name
    * @returns {boolean}
-   * @description Sets a default item.
    */
   setDefItem(name) {
     let isACCEPTED = false;
@@ -134,8 +134,8 @@ class THtmlStubItemsSet {
   }
 
   /**
+   * Resets a default item.
    * @returns {void}
-   * @description Resets a default item.
    */
   rstDefItem() {
     // // TODO: check if item is shown
@@ -143,9 +143,9 @@ class THtmlStubItemsSet {
   }
 
   /**
+   * Checks if an item exists.
    * @param {string} name - an element name
    * @returns {boolean}
-   * @description Checks if an item exists.
    */
   hasItem(name) {
     const _name = typeof name === 'string' ? name.trim() : '';
@@ -153,17 +153,17 @@ class THtmlStubItemsSet {
   }
 
   /**
+   * Checks if any items exists.
    * @returns {boolean}
-   * @description Checks if any items exists.
    */
   hasItems() {
     return this.#_items.size > 0;
   }
 
   /**
+   * Returns an item by its name.
    * @param {string} name - an element name
    * @returns {?HTMLElement}
-   * @description Returns an item by its name.
    */
   getItem(name) {
     const _name = typeof name === 'string' ? name.trim() : '';
@@ -172,11 +172,11 @@ class THtmlStubItemsSet {
   }
 
   /**
+   * Adds an item to an instance members.
    * @param {string} name - an element name
    * @param {HTMLElement} item - an element
    * @param {boolean} [opt=false] - flag indicating a force mode
    * @returns {boolean}
-   * @description Adds an item to an instance members.
    */
   addItem(name, item, opt) {
     const _name = typeof name === 'string' ? name.trim() : '';
@@ -192,9 +192,9 @@ class THtmlStubItemsSet {
   }
 
   /**
+   * Deletes an item from an instance members.
    * @param {string} name - an element name
    * @returns {boolean}
-   * @description Deletes an item from an instance members.
    */
   delItem(name) {
     let _name = '';
@@ -210,9 +210,9 @@ class THtmlStubItemsSet {
   }
 
   /**
+   * Shows an item.
    * @param {string} name - an element name
    * @returns {boolean}
-   * @description Shows an item.
    */
   showItem(name) {
     const item = this.getItem(name);
@@ -222,17 +222,17 @@ class THtmlStubItemsSet {
   }
 
   /**
+   * Shows a default item.
    * @returns {boolean}
-   * @description Shows a default item.
    */
   showDefItem() {
     return this.showItem(this.#_defItem);
   }
 
   /**
+   * Hides an item.
    * @param {string} name - an element name
    * @returns {boolean}
-   * @description Hides an item.
    */
   hideItem(name) {
     const item = this.getItem(name);
@@ -242,18 +242,18 @@ class THtmlStubItemsSet {
   }
 
   /**
+   * Hides a default item.
    * @returns {boolean}
-   * @description Hides a default item.
    */
   hideDefItem() {
     return this.hideItem(this.#_defItem);
   }
 
   /**
+   * Adds an items to an instance members.
    * @param {(Array|OBJ_stubEList)} data - an array of entries or special object
    * @param {(boolean|OPT_ldstubs)} [opt] - an options
    * @returns {number}
-   * @description Adds an items to an instance members.
    * @todo [since 0.0.25] deprecate use of `opt` as `boolean`
    * @todo [since v0.0.26] for `OPT_ldstubs` a `defaultItem`-option deprecated
    */

package/lib/html-helper-lib.js

@@ -1,4 +1,4 @@
-// [v0.1.041-20250509]
+// [v0.1.043-20250827]
 
 // === 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;
@@ -492,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.26",
+  "version": "0.0.27",
   "description": "A base HTML-helper library for js",
   "author": "ygracs <cs70th-om@rambler.ru>",
   "license": "MIT",
@@ -42,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"
   }
 }