@cntwg/html-helper 0.0.20 → 0.0.22

package/lib/html-helper-lib.js

@@ -1,4 +1,4 @@
-// [v0.1.020-20230801]
+// [v0.1.033-20240714]
 
 // === module init block ===
 
@@ -8,85 +8,182 @@ const {
   valueToIDString,
 } = require('@ygracs/bsfoc-lib-js');
 
+// === module extra block (helper functions) ===
+
+// === module main block ===
+
+/***
+ * (* constant definitions *)
+ */
+
 const CSS_CLASS_CURRENT = 'current';
 const CSS_CLASS_SELECTED = 'selected';
 const CSS_CLASS_ACTIVE = 'active';
 const CSS_CLASS_DISABLED = 'disabled';
 const CSS_CLASS_HIDDEN = 'hidden';
 
-// === module extra block (helper functions) ===
-
-// === module main block (function definitions) ===
+/***
+ * (* function definitions *)
+ */
 
-function isHTMLElement(obj){
+/**
+ * @function isHTMLElement
+ * @param {any}
+ * @return {bool}
+ * @description Checks if the given object is an instance of an `HTMLElement`.
+ */
+function isHTMLElement(obj) {
   return obj instanceof HTMLElement;
 };
 
-function isSelectedHTMLElement(obj){
+/**
+ * @function isSelectedHTMLElement
+ * @param {HTMLElement}
+ * @return {bool}
+ * @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);
 };
 
-function isCurrentHTMLElement(obj){
+/**
+ * @function isCurrentHTMLElement
+ * @param {HTMLElement}
+ * @return {bool}
+ * @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);
 };
 
-function isActiveHTMLElement(obj){
+/**
+ * @function isActiveHTMLElement
+ * @param {HTMLElement}
+ * @return {bool}
+ * @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);
 };
 
-function isHiddenHTMLElement(obj){
+/**
+ * @function isHiddenHTMLElement
+ * @param {HTMLElement}
+ * @return {bool}
+ * @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);
 };
 
-function hideHtmlElement(obj){
+/**
+ * @function hideHtmlElement
+ * @param {HTMLElement}
+ * @return {bool}
+ * @description Hides a given HTML-element.
+ */
+function hideHtmlElement(obj) {
   const isSUCCEED = isHTMLElement(obj);
   if (isSUCCEED) obj.classList.add(CSS_CLASS_HIDDEN);
   return isSUCCEED;
 };
 
-function showHtmlElement(obj){
+/**
+ * @function showHtmlElement
+ * @param {HTMLElement}
+ * @return {bool}
+ * @description Shows a given HTML-element.
+ */
+function showHtmlElement(obj) {
   const isSUCCEED = isHTMLElement(obj);
   if (isSUCCEED) obj.classList.remove(CSS_CLASS_HIDDEN);
   return isSUCCEED;
 };
 
-function selectHtmlElement(obj){
+/**
+ * @function selectHtmlElement
+ * @param {HTMLElement}
+ * @return {bool}
+ * @description Makes selected a given HTML-element.
+ */
+function selectHtmlElement(obj) {
   const isSUCCEED = isHTMLElement(obj);
   if (isSUCCEED) obj.classList.add(CSS_CLASS_SELECTED);
   return isSUCCEED;
 };
 
-function unselectHtmlElement(obj){
+/**
+ * @function unselectHtmlElement
+ * @param {HTMLElement}
+ * @return {bool}
+ * @description Makes unselected a given HTML-element.
+ */
+function unselectHtmlElement(obj) {
   const isSUCCEED = isHTMLElement(obj);
   if (isSUCCEED) obj.classList.remove(CSS_CLASS_SELECTED);
   return isSUCCEED;
 };
 
-function markHtmlElementAsCurrent(obj){
+/**
+ * @function markHtmlElementAsCurrent
+ * @param {HTMLElement}
+ * @return {bool} - `true` if succeed.
+ * @description Marks a given HTML-element as "current".
+ */
+function markHtmlElementAsCurrent(obj) {
   const isSUCCEED = isHTMLElement(obj);
   if (isSUCCEED) obj.classList.add(CSS_CLASS_CURRENT);
   return isSUCCEED;
 };
 
-function unmarkCurrentHtmlElement(obj){
+/**
+ * @function unmarkCurrentHtmlElement
+ * @param {HTMLElement}
+ * @return {bool}
+ * @description Unmarks a given HTML-element previous marked as "current".
+ */
+function unmarkCurrentHtmlElement(obj) {
   const isSUCCEED = isHTMLElement(obj);
   if (isSUCCEED) obj.classList.remove(CSS_CLASS_CURRENT);
   return isSUCCEED;
 };
 
-function markHtmlElementAsActive(obj){
+/**
+ * @function markHtmlElementAsActive
+ * @param {HTMLElement}
+ * @return {bool}
+ * @description Marks a given HTML-element as "active".
+ */
+function markHtmlElementAsActive(obj) {
   const isSUCCEED = isHTMLElement(obj);
   if (isSUCCEED) obj.classList.add(CSS_CLASS_ACTIVE);
   return isSUCCEED;
 };
 
-function unmarkActiveHtmlElement(obj){
+/**
+ * @function unmarkActiveHtmlElement
+ * @param {HTMLElement}
+ * @return {bool}
+ * @description Unmarks a given HTML-element previous marked as "active".
+ */
+function unmarkActiveHtmlElement(obj) {
   const isSUCCEED = isHTMLElement(obj);
   if (isSUCCEED) obj.classList.remove(CSS_CLASS_ACTIVE);
   return isSUCCEED;
 };
 
-function lockHtmlElement(obj){
+/**
+ * @function lockHtmlElement
+ * @param {HTMLElement}
+ * @return {bool}
+ * @description Disables a given HTML-element.
+ * @since v0.0.19
+ */
+function lockHtmlElement(obj) {
   let isSUCCEED = isHTMLElement(obj);
   if (isSUCCEED) {
     const { classList, tagName } = obj;
@@ -105,7 +202,14 @@ function lockHtmlElement(obj){
   return isSUCCEED;
 };
 
-function unlockHtmlElement(obj){
+/**
+ * @function unlockHtmlElement
+ * @param {HTMLElement}
+ * @return {bool}
+ * @description Enables a given HTML-element.
+ * @since v0.0.19
+ */
+function unlockHtmlElement(obj) {
   let isSUCCEED = isHTMLElement(obj);
   if (isSUCCEED) {
     const { classList, tagName } = obj;
@@ -124,19 +228,84 @@ function unlockHtmlElement(obj){
   return isSUCCEED;
 };
 
+/**
+ * @function inactivateHtmlElements
+ * @param {...HTMLElement}
+ * @return {none}
+ * @description Disables an HTML-elements given by a list of a function params.
+ */
 function inactivateHtmlElements(...args) {
   for (let item of args) {
     lockHtmlElement(item);
   };
 };
 
+/**
+ * @function activateHtmlElements
+ * @param {...HTMLElement}
+ * @return {none}
+ * @description Enables an HTML-elements given by a list of a function params.
+ */
 function activateHtmlElements(...args) {
   for (let item of args) {
     unlockHtmlElement(item);
   };
 };
 
-function readAsAttrValue(value){
+/**
+ * @function readAsTagName
+ * @param {any}
+ * @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) return '';
+  if (tagName !== '') {
+    // // TODO: do extra checks
+    const template = /[^\w]/;
+    const trigger = tagName.match(template);
+    if (trigger) {
+      //console.log(trigger);
+      tagName = '';
+    };
+    if (tagName !== '') tagName = tagName.toLowerCase();
+  };
+  return tagName;
+};
+
+/**
+ * @function readAsAttrName
+ * @param {any}
+ * @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) return '';
+  if (attrName !== '') {
+    // // TODO: do extra checks
+    const template = /[\s\/\\\"\'<>=]/;
+    const trigger = attrName.match(template);
+    if (trigger) {
+      //console.log(trigger);
+      attrName = '';
+    };
+  };
+  return attrName;
+};
+
+/**
+ * @function readAsAttrValue
+ * @param {any}
+ * @return {?string}
+ * @since v0.0.18
+ * @description Tries to convert a given value to a valid "attribute value".
+ */
+function readAsAttrValue(value) {
   let result = null;
   switch (typeof value) {
     case 'boolean': {
@@ -159,7 +328,16 @@ function readAsAttrValue(value){
   return result;
 };
 
-function valueToClassList(value, opt){
+/**
+ * @function valueToClassList
+ * @param {any}
+ * @param {bool} [opt]
+ * @return {array}
+ * @since v0.0.13
+ * @description Tries to convert a given value to a list of a valid
+ *              "class attributes".
+ */
+function valueToClassList(value, opt) {
   let result = [];
   let list = valueToArray(value);
   list.forEach((elem) => {
@@ -178,21 +356,63 @@ function valueToClassList(value, opt){
   return result;
 };
 
-function createNewHtmlElement(tagName, opt){
-  let _tag = typeof tagName === 'string' ? tagName.trim() : '';
+/**
+ * @function valueToElementID
+ * @param {any}
+ * @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.
+ */
+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;
+};
+
+/**
+ * @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]
+ * @return {?HTMLElement}
+ * @description Creates a new HTML-element.
+ */
+function createNewHtmlElement(tagName, opt) {
+  let item = null;
+  let _tag = readAsTagName(tagName);
   if (_tag === '') return null;
-  let item = document.createElement(_tag.toLowerCase());
-  if (isPlainObject(opt)) {
+  try {
+    item = document.createElement(_tag);
+  } catch (err) {
+    //console.log(`TEST IS_ERR: => ${err}`);
+    item = null;
+  } finally {
+    // // TODO:
+  };
+  if (item && isPlainObject(opt)) {
     let {
       id,
       text,
       attr,
-      classNames,
-      class: _class,
+      classNames: cl,
       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));
@@ -202,17 +422,27 @@ function createNewHtmlElement(tagName, opt){
       attr = isArray(attr) ? attr : Object.entries(attr);
       for (let [ key, value ] of attr ) {
         if (
-          ((key = valueToIDString(key)) !== null)
-          && ((value = readAsAttrValue(value)) !== null)
+          ((key = readAsAttrName(key)) !== '')
         ) {
-          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);
+            };
+          };
         };
       };
     };
     // set a class-attributes of the element
-    if (_class === undefined) _class = classNames;
-    if (_class !== undefined) {
-      const cl = valueToClassList(_class, true);
+    if (cl !== undefined) {
+      cl = valueToClassList(cl, true);
       if (cl.length > 0) item.classList.add(...cl);
     };
     // set a data-attributes of the element
@@ -220,7 +450,7 @@ function createNewHtmlElement(tagName, opt){
       dset = isArray(dset) ? dset : Object.entries(dset);
       for (let [ key, value ] of dset ) {
         if (
-          ((key = valueToIDString(key)) !== null)
+          ((key = readAsAttrName(key)) !== '')
           && ((value = readAsAttrValue(value)) !== null)
         ) {
           item.dataset[key] = value;
@@ -233,11 +463,13 @@ function createNewHtmlElement(tagName, opt){
   return item;
 };
 
-// === module main block (class definitions) ===
+/***
+ * (* class definitions *)
+ */
 
 // === module exports block ===
 
-exports.CSS_CLASS_STRING = /*function(){ return*/ {
+module.exports.CSS_CLASS_STRING = /*function(){ return*/ {
   CSS_CLASS_CURRENT: CSS_CLASS_CURRENT,
   CSS_CLASS_SELECTED: CSS_CLASS_SELECTED,
   CSS_CLASS_ACTIVE: CSS_CLASS_ACTIVE,
@@ -245,27 +477,32 @@ exports.CSS_CLASS_STRING = /*function(){ return*/ {
   CSS_CLASS_HIDDEN: CSS_CLASS_HIDDEN
 }/*}*/;
 
-exports.isHTMLElement = isHTMLElement;
-exports.isCurrentHTMLElement = isCurrentHTMLElement;
-exports.isSelectedHTMLElement = isSelectedHTMLElement;
-exports.isActiveHTMLElement = isActiveHTMLElement;
-exports.isHiddenHTMLElement = isHiddenHTMLElement;
-exports.showHtmlElement = showHtmlElement;
-exports.hideHtmlElement = hideHtmlElement;
-exports.selectHtmlElement = selectHtmlElement;
-exports.unselectHtmlElement = unselectHtmlElement;
-exports.markHtmlElementAsCurrent = markHtmlElementAsCurrent;
-exports.unmarkCurrentHtmlElement = unmarkCurrentHtmlElement;
-exports.markHtmlElementAsActive = markHtmlElementAsActive;
-exports.unmarkActiveHtmlElement = unmarkActiveHtmlElement;
-exports.lockHtmlElement = lockHtmlElement;
-exports.unlockHtmlElement = unlockHtmlElement;
-exports.activateHtmlElements = activateHtmlElements;
-exports.inactivateHtmlElements = inactivateHtmlElements;
-
-exports.valueToClassList = valueToClassList;
+module.exports.isHTMLElement = isHTMLElement;
+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
-exports.createNewHtmlElement = createNewHtmlElement;
-exports.valueToIDString = valueToIDString;
-exports.readAsAttrValue = readAsAttrValue;
+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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cntwg/html-helper",
-  "version": "0.0.20",
+  "version": "0.0.22",
   "description": "A base HTML-helper library for js",
   "author": "ygracs <cs70th-om@rambler.ru>",
   "license": "MIT",
@@ -8,6 +8,11 @@
     "type": "git",
     "url": "git+https://gitlab.com/cntwg/html-helper.git"
   },
+  "keywords": [
+    "electron",
+    "html",
+    "component"
+  ],
   "main": "./index.js",
   "files": [
     "doc/html-helper-lib.md",
@@ -40,17 +45,21 @@
     "test-lbc:ec": "jest THtmlListButtonsController/events",
     "test-bc1": "jest THtmlButtonsControllerARCSet",
     "test-bc1:bs": "jest THtmlButtonsControllerARCSet/base",
-    "test-bc1:ec": "jest THtmlButtonsControllerARCSet/events"
+    "test-bc1:ec": "jest THtmlButtonsControllerARCSet/events",
+    "build-doc-md": "jsdoc2md",
+    "build-doc-html": "jsdoc"
   },
   "imports": {
-    "#lib/*": "./lib/*"
+    "#lib/*": "./lib/*",
+    "#test-dir/*": "./__test__/*"
   },
   "dependencies": {
-    "@ygracs/bsfoc-lib-js": "^0.1.4"
+    "@ygracs/bsfoc-lib-js": "^0.2.1"
   },
   "devDependencies": {
-    "jest": "^29.6.2",
-    "jest-environment-jsdom": "^29.6.2",
+    "jest": "^29.7.0",
+    "jest-environment-jsdom": "^29.7.0",
+    "jsdoc-to-markdown": "^8.0.1",
     "minimist": "^1.2.8"
   }
 }