@cntwg/html-helper 0.1.2 → 0.1.4

package/CHANGELOG.md

@@ -1,3 +1,16 @@
+#### *v0.1.4*
+
+Release version.
+
+> - some fixes.
+
+#### *v0.1.3*
+
+Release version.
+
+> - `README.md` updated;
+> - some fixes.
+
 #### *v0.1.2*
 
 Release version.

package/README.md

@@ -1,6 +1,6 @@
->|***rev.*:**|0.2.8|
+>|***rev.*:**|0.2.9|
 >|:---|---:|
->|date:|2025-10-23|
+>|date:|2026-04-14|
 
 ## Introduction
 
@@ -36,3 +36,5 @@ This module was make for use as a library in a development of a Web-apps based o
 ### Installation
 
 `npm install @cntwg/html-helper`
+
+> Note: It's recommended to "pin" a package versions range to its minor releases after installation. To do so use `~` range specifier (*e.g. `~0.1.0`*) in `package.json`.

package/index.d.ts

@@ -0,0 +1,54 @@
+export namespace eventHelper {
+    let pushEventHandler: typeof ev_helper.pushEventHandler;
+    let removeEventHandler: typeof ev_helper.removeEventHandler;
+    let triggerEventHandler: typeof ev_helper.triggerEventHandler;
+}
+import { valueToIDString } from "@ygracs/bsfoc-lib-js";
+import ev_helper = require("./lib/event-hfunc.js");
+
+import {
+    CSS_CLASS_STRING,
+    isSelectedHTMLElement, isCurrentHTMLElement,
+    isActiveHTMLElement, isHiddenHTMLElement,
+    hideHTMLElement, showHTMLElement,
+    selectHTMLElement, unselectHTMLElement,
+    markHTMLElementAsCurrent, unmarkCurrentHTMLElement,
+    markHTMLElementAsActive, unmarkActiveHTMLElement,
+    lockHTMLElement, unlockHTMLElement,
+    activateHTMLElements, inactivateHTMLElements,
+    createNewHTMLElement,
+} from "./lib/html-helper-lib";
+
+import type {
+    IElementDesc,
+} from "./lib/html-helper-lib";
+
+import {
+    isHTMLElement, isHTMLButton,
+    valueToClassList,
+    readAsTagName, readAsAttrName, readAsAttrValue,
+    valueToElementID,
+} from "./lib/mod-hfunc";
+
+export {
+    CSS_CLASS_STRING,
+    isHTMLElement,
+    isSelectedHTMLElement, isCurrentHTMLElement,
+    isActiveHTMLElement, isHiddenHTMLElement,
+    hideHTMLElement, showHTMLElement,
+    selectHTMLElement, unselectHTMLElement,
+    markHTMLElementAsCurrent, unmarkCurrentHTMLElement,
+    markHTMLElementAsActive, unmarkActiveHTMLElement,
+    lockHTMLElement, unlockHTMLElement,
+    activateHTMLElements, inactivateHTMLElements,
+    valueToClassList,
+    readAsTagName, readAsAttrName, readAsAttrValue,
+    valueToElementID,
+    createNewHTMLElement,
+    isHTMLButton,
+    valueToIDString,
+};
+
+export type {
+    IElementDesc,
+};

package/index.js

@@ -1,9 +1,10 @@
-// [v0.2.034-20260309]
+// [v0.2.037-20260517]
 
 // === module init block ===
 
-const html_helper = require('./lib/html-helper-lib.js');
-const ev_helper = require('./lib/event-hfunc.js');
+const html_helper = require('./lib/html-helper-lib');
+const mod_helper = require('./lib/mod-hfunc');
+const ev_helper = require('./lib/event-hfunc');
 
 const {
   valueToIDString,
@@ -19,11 +20,19 @@ const eventHelper = {
   removeEventHandler: ev_helper.removeEventHandler,
   triggerEventHandler: ev_helper.triggerEventHandler,
 };
+module.exports.eventHelper = eventHelper;
 
 // === module exports block ===
 
+module.exports.isHTMLElement = mod_helper.isHTMLElement;
+module.exports.isHTMLButton = mod_helper.isHTMLButton;
+module.exports.readAsTagName = mod_helper.readAsTagName;
+module.exports.readAsAttrName = mod_helper.readAsAttrName;
+module.exports.readAsAttrValue = mod_helper.readAsAttrValue;
+module.exports.valueToElementID = mod_helper.valueToElementID;
+module.exports.valueToClassList = mod_helper.valueToClassList;
+
 module.exports.CSS_CLASS_STRING = html_helper.CSS_CLASS_STRING;
-module.exports.isHTMLElement = html_helper.isHTMLElement;
 module.exports.isSelectedHTMLElement = html_helper.isSelectedHTMLElement;
 module.exports.isCurrentHTMLElement = html_helper.isCurrentHTMLElement;
 module.exports.isActiveHTMLElement = html_helper.isActiveHTMLElement;
@@ -40,17 +49,10 @@ module.exports.lockHTMLElement = html_helper.lockHTMLElement;
 module.exports.unlockHTMLElement = html_helper.unlockHTMLElement;
 module.exports.activateHTMLElements = html_helper.activateHTMLElements;
 module.exports.inactivateHTMLElements = html_helper.inactivateHTMLElements;
-module.exports.valueToClassList = html_helper.valueToClassList;
 
-// * experimental *
-module.exports.readAsTagName = html_helper.readAsTagName;
-module.exports.readAsAttrName = html_helper.readAsAttrName;
-module.exports.readAsAttrValue = html_helper.readAsAttrValue;
-module.exports.valueToElementID = html_helper.valueToElementID;
 module.exports.createNewHTMLElement = html_helper.createNewHTMLElement;
-module.exports.isHTMLButton = html_helper.isHTMLButton;
-
-module.exports.eventHelper = eventHelper;
+// * exports types definitions *
+module.exports.IElementDesc = html_helper.IElementDesc;
 
 // * re-exported *
 module.exports.valueToIDString = valueToIDString;

package/lib/event-hfunc.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @inner
+ */
+export function pushEventHandler(pool: Map<string, Function>, name: string, evnt: Function): void;
+/**
+ * @inner
+ */
+export function removeEventHandler(pool: Map<string, Function>, name: string): void;
+/**
+ * @inner
+ */
+export function triggerEventHandler(pool: Map<string, Function>, name: string, ...args: any[]): void;

package/lib/event-hfunc.js

@@ -1,4 +1,4 @@
-// [v0.1.064-20260309]
+// [v0.1.065-20260413]
 
 // === module init block ===
 
@@ -50,14 +50,15 @@ module.exports.removeEventHandler = removeEventHandler;
  * @function triggerEventHandler
  * @param {Map<string, Function>} pool - pool object
  * @param {string} name - event name
- * @param {...any} [args]
+ * @param {...any} args - optional params send to a target event
  * @returns {void}
  * @inner
  */
 function triggerEventHandler(pool, name, ...args) {
-  const _name = typeof name === 'string' ? name.trim() : '';
-  if (_name !== '') {
-    if (pool.has(_name)) pool.get(_name)(...args);
+  const target = typeof name === 'string' ? name.trim() : '';
+  if (target !== '' && pool.has(target)) {
+    const e = pool.get(target);
+    if (typeof e === 'function') e(...args);
   };
 };
 module.exports.triggerEventHandler = triggerEventHandler;

package/lib/html-helper-lib.d.ts

@@ -0,0 +1,131 @@
+/**
+ * An element descriptor.
+ */
+export type IElementDesc = {
+    /**
+     * - element ID
+     */
+    id?: string;
+    /**
+     * - some text
+     */
+    text?: string;
+    /**
+     * - an attributes list
+     */
+    attr?: {
+        [x: string]: any;
+    };
+    /**
+     * - a class names list
+     * @since 0.0.19
+     */
+    classNames?: string | string[];
+    /**
+     * - a 'dataset'-attributes list
+     */
+    data?: {
+        [x: string]: any;
+    };
+};
+export const IElementDesc: IElementDesc;
+export namespace CSS_CLASS_STRING {
+    export { CSS_CLASS_CURRENT };
+    export { CSS_CLASS_SELECTED };
+    export { CSS_CLASS_ACTIVE };
+    export { CSS_CLASS_DISABLED };
+    export { CSS_CLASS_HIDDEN };
+}
+
+/**
+ * Checks if the given object is an instance of a `HTMLElement`
+ * and if so it's marked as "selected".
+ */
+export function isSelectedHTMLElement(obj: HTMLElement): boolean;
+/**
+ * Checks if the given object is an instance of a `HTMLElement`
+ * and if so it's marked as "current".
+ */
+export function isCurrentHTMLElement(obj: HTMLElement): boolean;
+/**
+ * Checks if the given object is an instance of a `HTMLElement`
+ * and if so it's marked as "active".
+ */
+export function isActiveHTMLElement(obj: HTMLElement): boolean;
+/**
+ * Checks if the given object is an instance of a `HTMLElement`
+ * and if so it's marked as "hidden".
+ */
+export function isHiddenHTMLElement(obj: HTMLElement): boolean;
+/**
+ * Hides a given HTML-element.
+ * @since v0.0.23
+ */
+export function hideHTMLElement(obj: HTMLElement): boolean;
+/**
+ * Shows a given HTML-element.
+ * @since v0.0.23
+ */
+export function showHTMLElement(obj: HTMLElement): boolean;
+/**
+ * Makes selected a given HTML-element.
+ * @since v0.0.23
+ */
+export function selectHTMLElement(obj: HTMLElement): boolean;
+/**
+ * Makes unselected a given HTML-element.
+ * @since v0.0.23
+ */
+export function unselectHTMLElement(obj: HTMLElement): boolean;
+/**
+ * Marks a given HTML-element as "current".
+ * @since v0.0.23
+ */
+export function markHTMLElementAsCurrent(obj: HTMLElement): boolean;
+/**
+ * Unmarks a given HTML-element previous marked as "current".
+ * @since v0.0.23
+ */
+export function unmarkCurrentHTMLElement(obj: HTMLElement): boolean;
+/**
+ * Marks a given HTML-element as "active".
+ * @since v0.0.23
+ */
+export function markHTMLElementAsActive(obj: HTMLElement): boolean;
+/**
+ * Unmarks a given HTML-element previous marked as "active".
+ * @since v0.0.23
+ */
+export function unmarkActiveHTMLElement(obj: HTMLElement): boolean;
+/**
+ * Disables a given HTML-element.
+ * @since v0.0.23
+ */
+export function lockHTMLElement(obj: HTMLElement): boolean;
+/**
+ * Enables a given HTML-element.
+ * @since v0.0.23
+ */
+export function unlockHTMLElement(obj: HTMLElement): boolean;
+/**
+ * Enables an HTML-elements given by a list of a function params.
+ * @since v0.0.23
+ */
+export function activateHTMLElements(...args: HTMLElement[]): void;
+/**
+ * Disables an HTML-elements given by a list of a function params.
+ * @since v0.0.23
+ */
+export function inactivateHTMLElements(...args: HTMLElement[]): void;
+/**
+ * Creates a new HTML-element.
+ * @since 0.0.25
+ * @experimental
+ */
+export function createNewHTMLElement(tagName: string, opt?: IElementDesc): HTMLElement | null;
+declare const CSS_CLASS_CURRENT: "current";
+declare const CSS_CLASS_SELECTED: "selected";
+declare const CSS_CLASS_ACTIVE: "active";
+declare const CSS_CLASS_DISABLED: "disabled";
+declare const CSS_CLASS_HIDDEN: "hidden";
+export {};

package/lib/html-helper-lib.js

@@ -1,17 +1,19 @@
-// [v0.1.046-20260309]
+// [v0.1.050-20260517]
 
 // === module init block ===
 
 const {
-  isArray, isObject, isPlainObject, valueToArray,
-  valueToIDString,
+  isArray, isObject, isPlainObject,
 } = require('@ygracs/bsfoc-lib-js');
 
-// === module inner block ===
+const {
+  isHTMLElement,
+  valueToElementID, valueToClassList,
+  readAsTagName,
+  readAsAttrName, readAsAttrValue,
+} = require('./mod-hfunc');
 
-const etlHTagInputForBtn = new Set([
-  'button', 'submit', 'reset', 'image',
-]);
+// === module inner block ===
 
 // === module main block ===
 
@@ -21,40 +23,6 @@ const CSS_CLASS_ACTIVE = 'active';
 const CSS_CLASS_DISABLED = 'disabled';
 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}
- */
-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".
@@ -65,6 +33,7 @@ function isHTMLButton(obj) {
 function isSelectedHTMLElement(obj) {
   return isHTMLElement(obj) && obj.classList.contains(CSS_CLASS_SELECTED);
 };
+module.exports.isSelectedHTMLElement = isSelectedHTMLElement;
 
 /**
  * Checks if the given object is an instance of a `HTMLElement`
@@ -76,6 +45,7 @@ function isSelectedHTMLElement(obj) {
 function isCurrentHTMLElement(obj) {
   return isHTMLElement(obj) && obj.classList.contains(CSS_CLASS_CURRENT);
 };
+module.exports.isCurrentHTMLElement = isCurrentHTMLElement;
 
 /**
  * Checks if the given object is an instance of a `HTMLElement`
@@ -87,6 +57,7 @@ function isCurrentHTMLElement(obj) {
 function isActiveHTMLElement(obj) {
   return isHTMLElement(obj) && obj.classList.contains(CSS_CLASS_ACTIVE);
 };
+module.exports.isActiveHTMLElement = isActiveHTMLElement;
 
 /**
  * Checks if the given object is an instance of a `HTMLElement`
@@ -98,6 +69,7 @@ function isActiveHTMLElement(obj) {
 function isHiddenHTMLElement(obj) {
   return isHTMLElement(obj) && obj.classList.contains(CSS_CLASS_HIDDEN);
 };
+module.exports.isHiddenHTMLElement = isHiddenHTMLElement;
 
 /**
  * Hides a given HTML-element.
@@ -111,6 +83,7 @@ function hideHTMLElement(obj) {
   if (isSUCCEED) obj.classList.add(CSS_CLASS_HIDDEN);
   return isSUCCEED;
 };
+module.exports.hideHTMLElement = hideHTMLElement;
 
 /**
  * Shows a given HTML-element.
@@ -124,6 +97,7 @@ function showHTMLElement(obj) {
   if (isSUCCEED) obj.classList.remove(CSS_CLASS_HIDDEN);
   return isSUCCEED;
 };
+module.exports.showHTMLElement = showHTMLElement;
 
 /**
  * Makes selected a given HTML-element.
@@ -137,6 +111,7 @@ function selectHTMLElement(obj) {
   if (isSUCCEED) obj.classList.add(CSS_CLASS_SELECTED);
   return isSUCCEED;
 };
+module.exports.selectHTMLElement = selectHTMLElement;
 
 /**
  * Makes unselected a given HTML-element.
@@ -150,6 +125,7 @@ function unselectHTMLElement(obj) {
   if (isSUCCEED) obj.classList.remove(CSS_CLASS_SELECTED);
   return isSUCCEED;
 };
+module.exports.unselectHTMLElement = unselectHTMLElement;
 
 /**
  * Marks a given HTML-element as "current".
@@ -163,6 +139,7 @@ function markHTMLElementAsCurrent(obj) {
   if (isSUCCEED) obj.classList.add(CSS_CLASS_CURRENT);
   return isSUCCEED;
 };
+module.exports.markHTMLElementAsCurrent = markHTMLElementAsCurrent;
 
 /**
  * Unmarks a given HTML-element previous marked as "current".
@@ -176,6 +153,7 @@ function unmarkCurrentHTMLElement(obj) {
   if (isSUCCEED) obj.classList.remove(CSS_CLASS_CURRENT);
   return isSUCCEED;
 };
+module.exports.unmarkCurrentHTMLElement = unmarkCurrentHTMLElement;
 
 /**
  * Marks a given HTML-element as "active".
@@ -189,6 +167,7 @@ function markHTMLElementAsActive(obj) {
   if (isSUCCEED) obj.classList.add(CSS_CLASS_ACTIVE);
   return isSUCCEED;
 };
+module.exports.markHTMLElementAsActive = markHTMLElementAsActive;
 
 /**
  * Unmarks a given HTML-element previous marked as "active".
@@ -202,6 +181,7 @@ function unmarkActiveHTMLElement(obj) {
   if (isSUCCEED) obj.classList.remove(CSS_CLASS_ACTIVE);
   return isSUCCEED;
 };
+module.exports.unmarkActiveHTMLElement = unmarkActiveHTMLElement;
 
 /**
  * Disables a given HTML-element.
@@ -226,6 +206,7 @@ function lockHTMLElement(obj) {
   };
   return isSUCCEED;
 };
+module.exports.lockHTMLElement = lockHTMLElement;
 
 /**
  * Enables a given HTML-element.
@@ -250,12 +231,13 @@ function unlockHTMLElement(obj) {
   };
   return isSUCCEED;
 };
+module.exports.unlockHTMLElement = unlockHTMLElement;
 
 /**
  * Enables an HTML-elements given by a list of a function params.
  * @since v0.0.23
  * @function activateHTMLElements
- * @param {...HTMLElement} obj - some element
+ * @param {...HTMLElement} args - some element
  * @return {void}
  */
 function activateHTMLElements(...args) {
@@ -263,12 +245,13 @@ function activateHTMLElements(...args) {
     unlockHTMLElement(item);
   };
 };
+module.exports.activateHTMLElements = activateHTMLElements;
 
 /**
  * Disables an HTML-elements given by a list of a function params.
  * @since v0.0.23
  * @function inactivateHTMLElements
- * @param {...HTMLElement} obj - some element
+ * @param {...HTMLElement} args - some element
  * @return {void}
  */
 function inactivateHTMLElements(...args) {
@@ -276,147 +259,31 @@ function inactivateHTMLElements(...args) {
     lockHTMLElement(item);
   };
 };
-
-/**
- * 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}
- */
-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;
-};
-
-/**
- * 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}
- */
-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;
-};
-
-/**
- * Tries to convert a given value to a valid "attribute value".
- * @since v0.0.18
- * @function readAsAttrValue
- * @param {any} value - some value
- * @return {?string}
- */
-function readAsAttrValue(value) {
-  let result = null;
-  switch (typeof value) {
-    case 'boolean': {
-      result = value.toString();
-      break;
-    }
-    case 'number': {
-      if (Number.isNaN(value)) break;
-      result = value.toString();
-      break;
-    }
-    case 'string': {
-      result = value.trim();
-      break;
-    }
-    default: {}
-  };
-  return result;
-};
-
-/**
- * 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[]}
- */
-function valueToClassList(value, opt) {
-  let result = [];
-  let list = valueToArray(value);
-  list.forEach((elem) => {
-    let value = '';
-    if (
-      typeof elem === 'string'
-      && ((value = elem.trim()) !== '')
-    ) {
-      value = value.split(/\s+/);
-      if (value.length > 0) result.push(...value);
-    };
-  });
-  if (result.length > 0 && typeof opt === 'boolean' && opt) {
-    result = [ ...(new Set(result)) ];
-  };
-  return result;
-};
-
-/**
- * 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}
- */
-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;
-};
+module.exports.inactivateHTMLElements = inactivateHTMLElements;
 
 /**
  * An element descriptor.
- * @typedef {Object} elemDesc
+ * @typedef {Object} IElementDesc
  * @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
  */
+/**
+ * A virtual constant meant for support jsdoc notation:
+ * @type {IElementDesc}
+ */
+module.exports.IElementDesc = {};
 
 /**
  * Creates a new HTML-element.
  * @since 0.0.25
  * @function createNewHTMLElement
  * @param {string} tagName - an element tag name
- * @param {elemDesc} [opt] - an element descriptor object
+ * @param {IElementDesc} [opt] - an element descriptor object
  * @return {?HTMLElement}
+ * @experimental
  */
 function createNewHTMLElement(tagName, opt) {
   let item = null;
@@ -446,8 +313,8 @@ function createNewHTMLElement(tagName, opt) {
     };
     // set an attributes of the element
     if (isObject(attr)) {
-      attr = isArray(attr) ? attr : Object.entries(attr);
-      for (let [ key, value ] of attr ) {
+      const data = isArray(attr) ? attr : Object.entries(attr);
+      for (let [ key, value ] of data ) {
         if (
           ((key = readAsAttrName(key)) !== '')
         ) {
@@ -474,8 +341,8 @@ function createNewHTMLElement(tagName, opt) {
     };
     // set a data-attributes of the element
     if (isObject(dset)) {
-      dset = isArray(dset) ? dset : Object.entries(dset);
-      for (let [ key, value ] of dset ) {
+      const data = isArray(dset) ? dset : Object.entries(dset);
+      for (let [ key, value ] of data ) {
         if (
           ((key = readAsAttrName(key)) !== '')
           && ((value = readAsAttrValue(value)) !== null)
@@ -489,6 +356,7 @@ function createNewHTMLElement(tagName, opt) {
   };
   return item;
 };
+module.exports.createNewHTMLElement = createNewHTMLElement;
 
 // === module exports block ===
 
@@ -499,32 +367,3 @@ module.exports.CSS_CLASS_STRING = /*function(){ return*/ {
   CSS_CLASS_DISABLED: CSS_CLASS_DISABLED,
   CSS_CLASS_HIDDEN: CSS_CLASS_HIDDEN
 }/*}*/;
-
-module.exports.isHTMLElement = isHTMLElement;
-module.exports.isHTMLButton = isHTMLButton;
-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;

package/lib/mod-hfunc.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Checks if the given object is an instance of an `HTMLElement`.
+ */
+export function isHTMLElement(obj: any): obj is HTMLElement;
+/**
+ * Checks if the given object is an HTML-button.
+ */
+export function isHTMLButton(obj: any): boolean;
+/**
+ * Tries to convert a given value to a valid name of an HTML-tag.
+ * @since v0.0.21
+ * @experimental
+ */
+export function readAsTagName(value: any): string;
+/**
+ * Tries to convert a given value to a valid name of an HTML-attribute.
+ * @since v0.0.21
+ * @experimental
+ */
+export function readAsAttrName(value: any): string;
+/**
+ * Tries to convert a given value to a valid "attribute value".
+ * @since v0.0.18
+ * @experimental
+ */
+export function readAsAttrValue(value: any): string | null;
+/**
+ * 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
+ * @experimental
+ */
+export function valueToElementID(value: any): string;
+/**
+ * Tries to convert a given value to a list of a valid "class attributes".
+ * @since v0.0.13
+ */
+export function valueToClassList(value: any, opt?: boolean): string[];

package/lib/mod-hfunc.js

@@ -0,0 +1,184 @@
+// [v0.1.048-20260517]
+
+// === module init block ===
+
+const {
+  valueToArray,
+  valueToIDString,
+} = require('@ygracs/bsfoc-lib-js');
+
+// === module inner block ===
+
+const etlHTagInputForBtn = new Set([
+  'button', 'submit', 'reset', 'image',
+]);
+
+// === module main block ===
+
+/**
+ * Checks if the given object is an instance of an `HTMLElement`.
+ * @function isHTMLElement
+ * @param {any} obj - some element
+ * @return {boolean}
+ */
+function isHTMLElement(obj) {
+  return obj instanceof HTMLElement;
+};
+module.exports.isHTMLElement = isHTMLElement;
+
+/**
+ * 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;
+}
+module.exports.isHTMLButton = isHTMLButton;
+
+/**
+ * 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}
+ * @experimental
+ */
+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;
+};
+module.exports.readAsTagName = readAsTagName;
+
+/**
+ * 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}
+ * @experimental
+ */
+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;
+};
+module.exports.readAsAttrName = readAsAttrName;
+
+/**
+ * Tries to convert a given value to a valid "attribute value".
+ * @since v0.0.18
+ * @function readAsAttrValue
+ * @param {any} value - some value
+ * @return {?string}
+ * @experimental
+ */
+function readAsAttrValue(value) {
+  let result = null;
+  switch (typeof value) {
+    case 'boolean': {
+      result = value.toString();
+      break;
+    }
+    case 'number': {
+      if (Number.isNaN(value)) break;
+      result = value.toString();
+      break;
+    }
+    case 'string': {
+      result = value.trim();
+      break;
+    }
+    default: {}
+  };
+  return result;
+};
+module.exports.readAsAttrValue = readAsAttrValue;
+
+/**
+ * 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}
+ * @experimental
+ */
+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;
+};
+module.exports.valueToElementID = valueToElementID;
+
+/**
+ * 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[]}
+ */
+function valueToClassList(value, opt) {
+  /** @type {string[]} */
+  let result = [];
+  valueToArray(value).forEach((elem) => {
+    let value = '';
+    if (
+      typeof elem === 'string'
+      && ((value = elem.trim()) !== '')
+    ) {
+      const a = value.split(/\s+/);
+      if (a.length > 0) result.push(...a);
+    };
+  });
+  if (result.length > 0 && typeof opt === 'boolean' && opt) {
+    result = [ ...(new Set(result)) ];
+  };
+  return result;
+};
+module.exports.valueToClassList = valueToClassList;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cntwg/html-helper",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "A base HTML-helper library for js",
   "author": "ygracs <cs70th-om@rambler.ru>",
   "license": "MIT",
@@ -13,11 +13,15 @@
     "html"
   ],
   "main": "./index.js",
+  "types": "./index.d.ts",
   "files": [
     "doc/*.md",
     "lib/html-helper-lib.js",
     "lib/event-hfunc.js",
+    "lib/mod-hfunc.js",
+    "lib/*.d.ts",
     "index.js",
+    "index.d.ts",
     "CHANGELOG.md"
   ],
   "scripts": {
@@ -26,7 +30,8 @@
     "test-bs:g1": "jest base/fg-1",
     "test-bs:g2": "jest base/fg-2",
     "build-doc-md": "jsdoc2md",
-    "build-doc-html": "jsdoc"
+    "build-doc-html": "jsdoc",
+    "gen-dts": "npx -p typescript tsc"
   },
   "imports": {
     "#lib/*": "./lib/*",
@@ -37,9 +42,10 @@
   },
   "devDependencies": {
     "@ygracs/test-helper": "~0.0.2-b",
-    "jest": "^30.2.0",
-    "jest-environment-jsdom": "^30.2.0",
+    "jest": "^30.4.2",
+    "jest-environment-jsdom": "^30.4.1",
     "jsdoc-to-markdown": "^9.1.3",
-    "minimist": "^1.2.8"
+    "minimist": "^1.2.8",
+    "typescript": "~5.9.3"
   }
 }