@cntwg/html-helper 0.0.22 → 0.0.23

package/lib/html-helper-lib.js

@@ -1,4 +1,4 @@
-// [v0.1.033-20240714]
+// [v0.1.036-20241110]
 
 // === module init block ===
 
@@ -28,8 +28,8 @@ const CSS_CLASS_HIDDEN = 'hidden';
 
 /**
  * @function isHTMLElement
- * @param {any}
- * @return {bool}
+ * @param {any} obj - some element
+ * @return {boolean}
  * @description Checks if the given object is an instance of an `HTMLElement`.
  */
 function isHTMLElement(obj) {
@@ -38,8 +38,8 @@ function isHTMLElement(obj) {
 
 /**
  * @function isSelectedHTMLElement
- * @param {HTMLElement}
- * @return {bool}
+ * @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".
  */
@@ -49,8 +49,8 @@ function isSelectedHTMLElement(obj) {
 
 /**
  * @function isCurrentHTMLElement
- * @param {HTMLElement}
- * @return {bool}
+ * @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".
  */
@@ -60,8 +60,8 @@ function isCurrentHTMLElement(obj) {
 
 /**
  * @function isActiveHTMLElement
- * @param {HTMLElement}
- * @return {bool}
+ * @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".
  */
@@ -71,8 +71,8 @@ function isActiveHTMLElement(obj) {
 
 /**
  * @function isHiddenHTMLElement
- * @param {HTMLElement}
- * @return {bool}
+ * @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".
  */
@@ -81,109 +81,157 @@ function isHiddenHTMLElement(obj) {
 };
 
 /**
- * @function hideHtmlElement
- * @param {HTMLElement}
- * @return {bool}
+ * @since v0.0.23
+ * @function hideHTMLElement
+ * @param {HTMLElement} obj - some element
+ * @return {boolean}
  * @description Hides a given HTML-element.
  */
-function hideHtmlElement(obj) {
+function hideHTMLElement(obj) {
   const isSUCCEED = isHTMLElement(obj);
   if (isSUCCEED) obj.classList.add(CSS_CLASS_HIDDEN);
   return isSUCCEED;
 };
 
+/** @deprecated */
+function hideHtmlElement(obj) {
+  return hideHTMLElement(obj);
+};
+
 /**
- * @function showHtmlElement
- * @param {HTMLElement}
- * @return {bool}
+ * @since v0.0.23
+ * @function showHTMLElement
+ * @param {HTMLElement} obj - some element
+ * @return {boolean}
  * @description Shows a given HTML-element.
  */
-function showHtmlElement(obj) {
+function showHTMLElement(obj) {
   const isSUCCEED = isHTMLElement(obj);
   if (isSUCCEED) obj.classList.remove(CSS_CLASS_HIDDEN);
   return isSUCCEED;
 };
 
+/** @deprecated */
+function showHtmlElement(obj) {
+  return showHTMLElement(obj);
+};
+
 /**
- * @function selectHtmlElement
- * @param {HTMLElement}
- * @return {bool}
+ * @since v0.0.23
+ * @function selectHTMLElement
+ * @param {HTMLElement} obj - some element
+ * @return {boolean}
  * @description Makes selected a given HTML-element.
  */
-function selectHtmlElement(obj) {
+function selectHTMLElement(obj) {
   const isSUCCEED = isHTMLElement(obj);
   if (isSUCCEED) obj.classList.add(CSS_CLASS_SELECTED);
   return isSUCCEED;
 };
 
+/** @deprecated */
+function selectHtmlElement(obj) {
+  return selectHTMLElement(obj);
+};
+
 /**
- * @function unselectHtmlElement
- * @param {HTMLElement}
- * @return {bool}
+ * @since v0.0.23
+ * @function unselectHTMLElement
+ * @param {HTMLElement} obj - some element
+ * @return {boolean}
  * @description Makes unselected a given HTML-element.
  */
-function unselectHtmlElement(obj) {
+function unselectHTMLElement(obj) {
   const isSUCCEED = isHTMLElement(obj);
   if (isSUCCEED) obj.classList.remove(CSS_CLASS_SELECTED);
   return isSUCCEED;
 };
 
+/** @deprecated */
+function unselectHtmlElement(obj) {
+  return unselectHTMLElement(obj);
+};
+
 /**
- * @function markHtmlElementAsCurrent
- * @param {HTMLElement}
- * @return {bool} - `true` if succeed.
+ * @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) {
+function markHTMLElementAsCurrent(obj) {
   const isSUCCEED = isHTMLElement(obj);
   if (isSUCCEED) obj.classList.add(CSS_CLASS_CURRENT);
   return isSUCCEED;
 };
 
+/** @deprecated */
+function markHtmlElementAsCurrent(obj) {
+  return markHTMLElementAsCurrent(obj);
+};
+
 /**
- * @function unmarkCurrentHtmlElement
- * @param {HTMLElement}
- * @return {bool}
+ * @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) {
+function unmarkCurrentHTMLElement(obj) {
   const isSUCCEED = isHTMLElement(obj);
   if (isSUCCEED) obj.classList.remove(CSS_CLASS_CURRENT);
   return isSUCCEED;
 };
 
+/** @deprecated */
+function unmarkCurrentHtmlElement(obj) {
+  return unmarkCurrentHTMLElement(obj);
+};
+
 /**
- * @function markHtmlElementAsActive
- * @param {HTMLElement}
- * @return {bool}
+ * @since v0.0.23
+ * @function markHTMLElementAsActive
+ * @param {HTMLElement} obj - some element
+ * @return {boolean}
  * @description Marks a given HTML-element as "active".
  */
-function markHtmlElementAsActive(obj) {
+function markHTMLElementAsActive(obj) {
   const isSUCCEED = isHTMLElement(obj);
   if (isSUCCEED) obj.classList.add(CSS_CLASS_ACTIVE);
   return isSUCCEED;
 };
 
+/** @deprecated */
+function markHtmlElementAsActive(obj) {
+  return markHTMLElementAsActive(obj);
+};
+
 /**
- * @function unmarkActiveHtmlElement
- * @param {HTMLElement}
- * @return {bool}
+ * @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) {
+function unmarkActiveHTMLElement(obj) {
   const isSUCCEED = isHTMLElement(obj);
   if (isSUCCEED) obj.classList.remove(CSS_CLASS_ACTIVE);
   return isSUCCEED;
 };
 
+/** @deprecated */
+function unmarkActiveHtmlElement(obj) {
+  return unmarkActiveHTMLElement(obj);
+};
+
 /**
- * @function lockHtmlElement
- * @param {HTMLElement}
- * @return {bool}
+ * @since v0.0.23
+ * @function lockHTMLElement
+ * @param {HTMLElement} obj - some element
+ * @return {boolean}
  * @description Disables a given HTML-element.
- * @since v0.0.19
  */
-function lockHtmlElement(obj) {
+function lockHTMLElement(obj) {
   let isSUCCEED = isHTMLElement(obj);
   if (isSUCCEED) {
     const { classList, tagName } = obj;
@@ -202,14 +250,19 @@ function lockHtmlElement(obj) {
   return isSUCCEED;
 };
 
+/** @deprecated */
+function lockHtmlElement(obj) {
+  return lockHTMLElement(obj);
+};
+
 /**
- * @function unlockHtmlElement
- * @param {HTMLElement}
- * @return {bool}
+ * @since v0.0.23
+ * @function unlockHTMLElement
+ * @param {HTMLElement} obj - some element
+ * @return {boolean}
  * @description Enables a given HTML-element.
- * @since v0.0.19
  */
-function unlockHtmlElement(obj) {
+function unlockHTMLElement(obj) {
   let isSUCCEED = isHTMLElement(obj);
   if (isSUCCEED) {
     const { classList, tagName } = obj;
@@ -228,35 +281,52 @@ function unlockHtmlElement(obj) {
   return isSUCCEED;
 };
 
+/** @deprecated */
+function unlockHtmlElement(obj) {
+  return unlockHTMLElement(obj);
+};
+
 /**
- * @function inactivateHtmlElements
- * @param {...HTMLElement}
- * @return {none}
- * @description Disables 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 inactivateHtmlElements(...args) {
+function activateHTMLElements(...args) {
   for (let item of args) {
-    lockHtmlElement(item);
+    unlockHTMLElement(item);
   };
 };
 
+/** @deprecated */
+function activateHtmlElements(...args) {
+  activateHTMLElements(...args);
+};
+
 /**
- * @function activateHtmlElements
- * @param {...HTMLElement}
- * @return {none}
- * @description Enables 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 activateHtmlElements(...args) {
+function inactivateHTMLElements(...args) {
   for (let item of args) {
-    unlockHtmlElement(item);
+    lockHTMLElement(item);
   };
 };
 
+/** @deprecated */
+function inactivateHtmlElements(...args) {
+  inactivateHTMLElements(...args);
+};
+
 /**
+ * @since v0.0.21
  * @function readAsTagName
- * @param {any}
+ * @param {any} value - some value
  * @return {string}
- * @since v0.0.21
  * @description Tries to convert a given value to a valid name of an HTML-tag.
  */
 function readAsTagName(value) {
@@ -276,10 +346,10 @@ function readAsTagName(value) {
 };
 
 /**
+ * @since v0.0.21
  * @function readAsAttrName
- * @param {any}
+ * @param {any} value - some value
  * @return {string}
- * @since v0.0.21
  * @description Tries to convert a given value to a valid name
  *              of an HTML-attribute.
  */
@@ -299,10 +369,10 @@ function readAsAttrName(value) {
 };
 
 /**
+ * @since v0.0.18
  * @function readAsAttrValue
- * @param {any}
+ * @param {any} value - some value
  * @return {?string}
- * @since v0.0.18
  * @description Tries to convert a given value to a valid "attribute value".
  */
 function readAsAttrValue(value) {
@@ -329,11 +399,11 @@ function readAsAttrValue(value) {
 };
 
 /**
- * @function valueToClassList
- * @param {any}
- * @param {bool} [opt]
- * @return {array}
  * @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".
  */
@@ -357,10 +427,10 @@ function valueToClassList(value, opt) {
 };
 
 /**
+ * @since v0.0.22
  * @function valueToElementID
- * @param {any}
+ * @param {any} value - some value
  * @return {string}
- * @since v0.0.22
  * @description Tries to convert a given value to a valid identifier
  *              suitable as a value for an "ID-attribute" of an HTML-element.
  */
@@ -379,15 +449,20 @@ function valueToElementID(value) {
   return id;
 };
 
+/**
+ * @typedef {Object} elemDesc
+ * @property {string} [id] - element ID
+ * @property {string} [text] - some text
+ * @property {object} [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.
+ */
+
 /**
  * @function createNewHtmlElement
- * @param {string}
- * @param {object} [opt]
- * @param {string} [opt.id]
- * @param {string} [opt.text]
- * @param {object} [opt.attr]
- * @param {string|array} [opt.classNames] (added since v0.0.19),
- * @param {object} [opt.data]
+ * @param {string} tagName - an element tag name
+ * @param {elemDesc} [opt] - an element description object
  * @return {?HTMLElement}
  * @description Creates a new HTML-element.
  */
@@ -482,18 +557,19 @@ module.exports.isCurrentHTMLElement = isCurrentHTMLElement;
 module.exports.isSelectedHTMLElement = isSelectedHTMLElement;
 module.exports.isActiveHTMLElement = isActiveHTMLElement;
 module.exports.isHiddenHTMLElement = isHiddenHTMLElement;
-module.exports.showHtmlElement = showHtmlElement;
-module.exports.hideHtmlElement = hideHtmlElement;
-module.exports.selectHtmlElement = selectHtmlElement;
-module.exports.unselectHtmlElement = unselectHtmlElement;
-module.exports.markHtmlElementAsCurrent = markHtmlElementAsCurrent;
-module.exports.unmarkCurrentHtmlElement = unmarkCurrentHtmlElement;
-module.exports.markHtmlElementAsActive = markHtmlElementAsActive;
-module.exports.unmarkActiveHtmlElement = unmarkActiveHtmlElement;
-module.exports.lockHtmlElement = lockHtmlElement;
-module.exports.unlockHtmlElement = unlockHtmlElement;
-module.exports.activateHtmlElements = activateHtmlElements;
-module.exports.inactivateHtmlElements = inactivateHtmlElements;
+
+module.exports.showHTMLElement = showHTMLElement;
+module.exports.hideHTMLElement = hideHTMLElement;
+module.exports.selectHTMLElement = selectHTMLElement;
+module.exports.unselectHTMLElement = unselectHTMLElement;
+module.exports.markHTMLElementAsCurrent = markHTMLElementAsCurrent;
+module.exports.unmarkCurrentHTMLElement = unmarkCurrentHTMLElement;
+module.exports.markHTMLElementAsActive = markHTMLElementAsActive;
+module.exports.unmarkActiveHTMLElement = unmarkActiveHTMLElement;
+module.exports.lockHTMLElement = lockHTMLElement;
+module.exports.unlockHTMLElement = unlockHTMLElement;
+module.exports.activateHTMLElements = activateHTMLElements;
+module.exports.inactivateHTMLElements = inactivateHTMLElements;
 
 module.exports.valueToClassList = valueToClassList;
 
@@ -506,3 +582,17 @@ module.exports.valueToElementID = valueToElementID;
 
 // re-exported
 module.exports.valueToIDString = valueToIDString;
+
+// @deprecated
+module.exports.showHtmlElement = showHtmlElement;
+module.exports.hideHtmlElement = hideHtmlElement;
+module.exports.selectHtmlElement = selectHtmlElement;
+module.exports.unselectHtmlElement = unselectHtmlElement;
+module.exports.markHtmlElementAsCurrent = markHtmlElementAsCurrent;
+module.exports.unmarkCurrentHtmlElement = unmarkCurrentHtmlElement;
+module.exports.markHtmlElementAsActive = markHtmlElementAsActive;
+module.exports.unmarkActiveHtmlElement = unmarkActiveHtmlElement;
+module.exports.lockHtmlElement = lockHtmlElement;
+module.exports.unlockHtmlElement = unlockHtmlElement;
+module.exports.activateHtmlElements = activateHtmlElements;
+module.exports.inactivateHtmlElements = inactivateHtmlElements;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cntwg/html-helper",
-  "version": "0.0.22",
+  "version": "0.0.23",
   "description": "A base HTML-helper library for js",
   "author": "ygracs <cs70th-om@rambler.ru>",
   "license": "MIT",
@@ -15,17 +15,15 @@
   ],
   "main": "./index.js",
   "files": [
-    "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",
+    "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",
     "CHANGELOG.md"
   ],
@@ -59,7 +57,7 @@
   "devDependencies": {
     "jest": "^29.7.0",
     "jest-environment-jsdom": "^29.7.0",
-    "jsdoc-to-markdown": "^8.0.1",
+    "jsdoc-to-markdown": "^9.0.5",
     "minimist": "^1.2.8"
   }
 }