@cntwg/html-helper 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+#### *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,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,9 @@
-// [v0.2.034-20260309]
+// [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,
@@ -19,6 +19,7 @@ const eventHelper = {
   removeEventHandler: ev_helper.removeEventHandler,
   triggerEventHandler: ev_helper.triggerEventHandler,
 };
+module.exports.eventHelper = eventHelper;
 
 // === module exports block ===
 
@@ -50,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 = 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,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.046-20260309]
+// [v0.1.047-20260413]
 
 // === module init block ===
 
@@ -255,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) {
@@ -268,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) {
@@ -359,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) {
@@ -446,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)) !== '')
         ) {
@@ -474,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)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cntwg/html-helper",
-  "version": "0.1.2",
+  "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,7 +29,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 +41,10 @@
   },
   "devDependencies": {
     "@ygracs/test-helper": "~0.0.2-b",
-    "jest": "^30.2.0",
-    "jest-environment-jsdom": "^30.2.0",
+    "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"
   }
 }