@cntwg/html-helper 0.0.21 → 0.0.23

package/lib/html-helper-lib.js

@@ -1,4 +1,4 @@
-// [v0.1.031-20240713]
+// [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,40 +281,58 @@ 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) {
   let tagName = valueToIDString(value, { ignoreNumbers: true });
-  if (tagName !== null && tagName !== '') {
+  if (tagName === null) return '';
+  if (tagName !== '') {
     // // TODO: do extra checks
     const template = /[^\w]/;
     const trigger = tagName.match(template);
@@ -271,20 +342,21 @@ function readAsTagName(value) {
     };
     if (tagName !== '') tagName = tagName.toLowerCase();
   };
-  return tagName === null ? '' : tagName;
+  return tagName;
 };
 
 /**
+ * @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.
  */
 function readAsAttrName(value) {
   let attrName = valueToIDString(value, { ignoreNumbers: true });
-  if (attrName !== null && attrName !== '') {
+  if (attrName === null) return '';
+  if (attrName !== '') {
     // // TODO: do extra checks
     const template = /[\s\/\\\"\'<>=]/;
     const trigger = attrName.match(template);
@@ -293,12 +365,13 @@ function readAsAttrName(value) {
       attrName = '';
     };
   };
-  return attrName === null ? '' : attrName;
+  return attrName;
 };
 
 /**
+ * @since v0.0.18
  * @function readAsAttrValue
- * @param {any}
+ * @param {any} value - some value
  * @return {?string}
  * @description Tries to convert a given value to a valid "attribute value".
  */
@@ -326,10 +399,11 @@ function readAsAttrValue(value) {
 };
 
 /**
+ * @since v0.0.13
  * @function valueToClassList
- * @param {any}
- * @param {bool} [opt]
- * @return {array}
+ * @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".
  */
@@ -352,15 +426,43 @@ function valueToClassList(value, opt) {
   return result;
 };
 
+/**
+ * @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);
+  if (id === null) return '';
+  if (id !== '') {
+    // // TODO: do extra checks
+    const template = /[\s\/\\\"\'<>=]/;
+    const trigger = id.match(template);
+    if (trigger) {
+      //console.log(trigger);
+      id = '';
+    };
+  };
+  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.
  */
@@ -385,7 +487,7 @@ function createNewHtmlElement(tagName, opt) {
       data: dset,
     } = opt;
     // set an element id
-    if ((id = valueToIDString(id)) !== null) item.setAttribute('id', id);
+    if ((id = valueToElementID(id)) !== '') item.setAttribute('id', id);
     // set an element text context
     if (typeof text === 'string') {
       item.appendChild(document.createTextNode(text));
@@ -396,9 +498,20 @@ function createNewHtmlElement(tagName, opt) {
       for (let [ key, value ] of attr ) {
         if (
           ((key = readAsAttrName(key)) !== '')
-          && ((value = readAsAttrValue(value)) !== null)
         ) {
-          item.setAttribute(key.toLowerCase(), value);
+          key = key.toLowerCase();
+          if (key === 'id') {
+            if (
+              id === ''
+              && ((value = valueToElementID(value)) !== '')
+            ) {
+              item.setAttribute('id', value);
+            };
+          } else {
+            if ((value = readAsAttrValue(value)) !== null) {
+              item.setAttribute(key, value);
+            };
+          };
         };
       };
     };
@@ -444,6 +557,33 @@ 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.valueToClassList = valueToClassList;
+
+// experimental
+module.exports.createNewHtmlElement = createNewHtmlElement;
+module.exports.readAsAttrValue = readAsAttrValue;
+module.exports.readAsTagName = readAsTagName;
+module.exports.readAsAttrName = readAsAttrName;
+module.exports.valueToElementID = valueToElementID;
+
+// re-exported
+module.exports.valueToIDString = valueToIDString;
+
+// @deprecated
 module.exports.showHtmlElement = showHtmlElement;
 module.exports.hideHtmlElement = hideHtmlElement;
 module.exports.selectHtmlElement = selectHtmlElement;
@@ -456,14 +596,3 @@ module.exports.lockHtmlElement = lockHtmlElement;
 module.exports.unlockHtmlElement = unlockHtmlElement;
 module.exports.activateHtmlElements = activateHtmlElements;
 module.exports.inactivateHtmlElements = inactivateHtmlElements;
-
-module.exports.valueToClassList = valueToClassList;
-
-// experimental
-module.exports.createNewHtmlElement = createNewHtmlElement;
-module.exports.readAsAttrValue = readAsAttrValue;
-module.exports.readAsTagName = readAsTagName;
-module.exports.readAsAttrName = readAsAttrName;
-
-// re-exported
-module.exports.valueToIDString = valueToIDString;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cntwg/html-helper",
-  "version": "0.0.21",
+  "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"
   }
 }