@cntwg/html-helper 0.1.1 → 0.1.3

package/CHANGELOG.md

@@ -1,3 +1,16 @@
+#### *v0.1.3*
+
+Release version.
+
+> - `README.md` updated;
+> - some fixes.
+
+#### *v0.1.2*
+
+Release version.
+
+> - update dependency on `@ygracs/bsfoc-lib-js` module to v0.3.4.
+
 #### *v0.1.1*
 
 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,44 @@
+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,
+    isHTMLElement,
+    isSelectedHTMLElement, isCurrentHTMLElement,
+    isActiveHTMLElement, isHiddenHTMLElement,
+    hideHTMLElement, showHTMLElement,
+    selectHTMLElement, unselectHTMLElement,
+    markHTMLElementAsCurrent, unmarkCurrentHTMLElement,
+    markHTMLElementAsActive, unmarkActiveHTMLElement,
+    lockHTMLElement, unlockHTMLElement,
+    activateHTMLElements, inactivateHTMLElements,
+    valueToClassList,
+    readAsTagName, readAsAttrName, readAsAttrValue,
+    valueToElementID,
+    createNewHTMLElement,
+    isHTMLButton,
+} from "./lib/html-helper-lib.js";
+
+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,
+};

package/index.js

@@ -1,9 +1,13 @@
-// [v0.2.033-20251023]
+// [v0.2.035-20260413]
 
 // === 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 ev_helper = require('./lib/event-hfunc');
+
+const {
+  valueToIDString,
+} = require('@ygracs/bsfoc-lib-js');
 
 
 // === module inner block ===
@@ -15,6 +19,7 @@ const eventHelper = {
   removeEventHandler: ev_helper.removeEventHandler,
   triggerEventHandler: ev_helper.triggerEventHandler,
 };
+module.exports.eventHelper = eventHelper;
 
 // === module exports block ===
 
@@ -46,7 +51,5 @@ module.exports.valueToElementID = html_helper.valueToElementID;
 module.exports.createNewHTMLElement = html_helper.createNewHTMLElement;
 module.exports.isHTMLButton = html_helper.isHTMLButton;
 
-module.exports.eventHelper = eventHelper;
-
 // * re-exported *
-module.exports.valueToIDString = html_helper.valueToIDString;
+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,19 +1,11 @@
-// [v0.1.063-20250503]
+// [v0.1.065-20260413]
 
 // === module init block ===
 
-// === module extra block (helper functions) ===
+// === module inner block ===
 
 // === module main block ===
 
-/***
- * (* constant definitions *)
- */
-
-/***
- * (* function definitions *)
- */
-
 /**
  * @function pushEventHandler
  * @param {Map<string, Function>} pool - pool object
@@ -34,6 +26,7 @@ function pushEventHandler(pool, name, evnt) {
     };
   };
 };
+module.exports.pushEventHandler = pushEventHandler;
 
 /**
  * @function removeEventHandler
@@ -51,28 +44,21 @@ function removeEventHandler(pool, name) {
     if (pool.has(key)) pool.delete(key);
   };
 };
+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);
   };
 };
-
-/***
- * (* class definitions *)
- */
-
-// === module exports block ===
-
-module.exports.pushEventHandler = pushEventHandler;
 module.exports.triggerEventHandler = triggerEventHandler;
-module.exports.removeEventHandler = removeEventHandler;

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

@@ -0,0 +1,165 @@
+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 };
+}
+
+/**
+ * An element descriptor.
+ */
+export type elemDesc = {
+    /**
+     * - 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;
+    };
+};
+
+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";
+
+/**
+ * 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;
+/**
+ * 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 "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 "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;
+/**
+ * Shows a given HTML-element.
+ * @since v0.0.23
+ */
+export function showHTMLElement(obj: HTMLElement): boolean;
+/**
+ * Hides a given HTML-element.
+ * @since v0.0.23
+ */
+export function hideHTMLElement(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;
+/**
+ * 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[];
+/**
+ * Creates a new HTML-element.
+ * @since 0.0.25
+ */
+export function createNewHTMLElement(tagName: string, opt?: elemDesc): HTMLElement | null;
+/**
+ * Tries to convert a given value to a valid "attribute value".
+ * @since v0.0.18
+ */
+export function readAsAttrValue(value: any): string | null;
+/**
+ * Tries to convert a given value to a valid name of an HTML-tag.
+ * @since v0.0.21
+ */
+export function readAsTagName(value: any): string;
+/**
+ * Tries to convert a given value to a valid name of an HTML-attribute.
+ * @since v0.0.21
+ */
+export function readAsAttrName(value: any): string;
+/**
+ * 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
+ */
+export function valueToElementID(value: any): string;
+export {};

package/lib/html-helper-lib.js

@@ -1,4 +1,4 @@
-// [v0.1.044-20251023]
+// [v0.1.047-20260413]
 
 // === module init block ===
 
@@ -15,20 +15,12 @@ const etlHTagInputForBtn = new Set([
 
 // === 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';
 
-/***
- * (* function definitions *)
- */
-
 /**
  * Checks if the given object is an instance of an `HTMLElement`.
  * @function isHTMLElement
@@ -263,7 +255,7 @@ 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
+ * @param {...HTMLElement} args - some element
  * @return {void}
  */
 function activateHTMLElements(...args) {
@@ -276,7 +268,7 @@ 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
+ * @param {...HTMLElement} args - some element
  * @return {void}
  */
 function inactivateHTMLElements(...args) {
@@ -367,16 +359,16 @@ function readAsAttrValue(value) {
  * @return {string[]}
  */
 function valueToClassList(value, opt) {
+  /** @type {string[]} */
   let result = [];
-  let list = valueToArray(value);
-  list.forEach((elem) => {
+  valueToArray(value).forEach((elem) => {
     let value = '';
     if (
       typeof elem === 'string'
       && ((value = elem.trim()) !== '')
     ) {
-      value = value.split(/\s+/);
-      if (value.length > 0) result.push(...value);
+      const a = value.split(/\s+/);
+      if (a.length > 0) result.push(...a);
     };
   });
   if (result.length > 0 && typeof opt === 'boolean' && opt) {
@@ -454,8 +446,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)) !== '')
         ) {
@@ -482,8 +474,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)
@@ -498,10 +490,6 @@ function createNewHTMLElement(tagName, opt) {
   return item;
 };
 
-/***
- * (* class definitions *)
- */
-
 // === module exports block ===
 
 module.exports.CSS_CLASS_STRING = /*function(){ return*/ {
@@ -540,6 +528,3 @@ 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.1.1",
+  "version": "0.1.3",
   "description": "A base HTML-helper library for js",
   "author": "ygracs <cs70th-om@rambler.ru>",
   "license": "MIT",
@@ -13,11 +13,14 @@
     "html"
   ],
   "main": "./index.js",
+  "types": "./index.d.ts",
   "files": [
     "doc/*.md",
     "lib/html-helper-lib.js",
     "lib/event-hfunc.js",
+    "lib/*.d.ts",
     "index.js",
+    "index.d.ts",
     "CHANGELOG.md"
   ],
   "scripts": {
@@ -26,19 +29,22 @@
     "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/*",
     "#test-dir/*": "./__test__/*"
   },
   "dependencies": {
-    "@ygracs/bsfoc-lib-js": "^0.3.3"
+    "@ygracs/bsfoc-lib-js": "~0.3.4"
   },
   "devDependencies": {
-    "jest": "^30.2.0",
-    "jest-environment-jsdom": "^30.2.0",
+    "@ygracs/test-helper": "~0.0.2-b",
+    "jest": "^30.3.0",
+    "jest-environment-jsdom": "^30.3.0",
     "jsdoc-to-markdown": "^9.1.3",
-    "minimist": "^1.2.8"
+    "minimist": "^1.2.8",
+    "typescript": "~5.9.3"
   }
 }