@cntwg/html-helper 0.0.25 → 0.0.27

package/CHANGELOG.md

@@ -1,3 +1,22 @@
+#### *v0.0.27*
+
+Pre-release version.
+
+> - `html-helper-lib.md` updated;
+> - `html-ctrls-btn.md` updated;
+> - update dependency on `@ygracs/bsfoc-lib-js` module to v0.3.0;
+> - update dependency on `@ygracs/lists-lib-js` module to v0.1.0.
+
+#### *v0.0.26*
+
+Pre-release version.
+
+> - `html-ctrls-list.md` updated;
+> - improve a 'THtmlItemsListController' behavior on handling a `click`-event;
+> - change behavior for a `THtmlStubItemsSet`-class constructor (*see docs for details*);
+> - change behavior for a `loadItems`-method of a `THtmlStubItemsSet`-class (*see docs for details*);
+> - some other fixes.
+
 #### *v0.0.25*
 
 Pre-release version.

package/doc/html-ctrls-btn.md

@@ -1,6 +1,6 @@
->|***rev.*:**|0.1.15|
+>|***rev.*:**|0.1.16|
 >|:---|---:|
->|date:|2024-11-15|
+>|date:|2025-08-27|
 
 ## Introduction
 
@@ -16,15 +16,6 @@ By module, constants that is provided listed in the following table:
 
 ## Module functions
 
-<a name="isHTMLButton"></a>
-#### **isHTMLButton(obj)** => `boolean`
-
-This function checks whether or not a given object represents an HTML-button element and if so returns `true` or `false` if else.
-
-| parameter name | value type | default value | description |
-|:---|---|---:|:---|
-| `obj` | `any` | --- | some element to be checked |
-
 ## Module classes
 
 <a name="THtmlButtonsSet"></a>
@@ -199,6 +190,8 @@ This method inactivates all "button" elements present in a group named by `name`
 |---|---|:---|
 | `function` | yes | contains a default function that verified validity of an element. The function receives element and returns result for validation as a `boolean`. |
 
+> For more details see [`isHTMLButton`](html-helper-lib.md#isHTMLButton).
+
 <a name="THtmlButtonsControllerARCSet"></a>
 ### **THtmlButtonsControllerARCSet**
 

package/doc/html-ctrls-list.md

@@ -1,6 +1,6 @@
->|***rev.*:**|0.1.23|
+>|***rev.*:**|0.1.24|
 >|:---|---:|
->|date:|2025-04-16|
+>|date:|2025-05-05|
 
 ## Introduction
 
@@ -625,7 +625,9 @@ The class constructor receives a parameters listed below:
 | parameter name | value type | default value | description |
 |:---|---|---:|:---|
 | `host` | `HTMLElement` | --- | points to a host element which holds a list items |
-| `options` | `object`, `array` | `undefined` | contains an object that is send to a class `loadItems` method |
+| `options` | `object`, `array` | --- | contains an object that is send to a class `loadItems` method |
+
+> \[!] NOTE: `[since v0.0.26]` a use of a `array` type as a value of an `options` are deprecated and will be dropped soon.
 
 ##### `options` parameter
 
@@ -633,11 +635,9 @@ The `options` structure has listed below:
 
 | option name | value type | default value | description |
 |:---|---|---:|:---|
-| `items` | `array` | `undefined` | defines a list of the entries to load. Each entry contains a `name`-`element` pair. |
+| `items` | `array`, `object` | --- | defines a list of the entries to load. For more details see a description of a [`loadItems`](#THtmlStubItemsSet+loadItems) class method |
 | `defaultItem` | `string` | --- | if set it defines a name of the item used by default |
-| `force` | `boolean` | `false` | if set to `true`, the item which is already present will be replaced with a new one (*`since: v0.0.23` - deprecated*) |
-
-> NOTE: For more details on an `items` element see an description of a [`loadItems`](#THtmlStubItemsSet+loadItems) class method.
+| `force` | `boolean` | `false` | if set to `true`, the item which is already present will be replaced with a new one |
 
 #### class properties
 
@@ -754,27 +754,27 @@ This class method is similar to `showItem` method but is performed on a default
 This class method is similar to `hideItem` method but is performed on a default item.
 
 <a name="THtmlStubItemsSet+loadItems"></a>
-##### **loadItems(list\[, options])** => `number`
+##### **loadItems(data\[, options])** => `number`
 
 This class methods loads an items given by `list` in the set and returned quantity of how many items have been processed successfully.
 
 | parameter name | value type | default value | description |
 |:---|---|---:|:---|
-| `list` | `array`, `object` | --- | an array of entries or a special descriptive object |
+| `data` | `array`, `object` | --- | an array of entries or a special descriptive object |
 | `options` | `boolean`, `object` | --- | an options |
 
 > \[!] NOTE: *`[since v0.0.25]`* the use of a booleans as an `options` value is deprecated and will be dropped soon.
 
-If the `list` parameter is an `object` that contains the following set of values:
+If the `data` parameter is an `object` that contains the following set of values:
 
 | option name | value type | default value | description |
 |:---|---|---:|:---|
 | `items` | `array` | `undefined` | defines a list of the entries to load. Each entry contains a `name`-`element` pair. |
 | `defaultItem` | `string` | --- | if set it defines a name of the item used by default |
 
-If the `list` parameter is an `array` it used as value of a `list.items` options and in such a case the name for a default element receives from an `options.defaultItem` if given.
+If the `data` parameter is an `array` it used as value of a `data.items` options.
 
-Note that each element of a `list.items` can be:
+Note that each element of a `data.items` can be:
 
 - an `array` which contains a `key-value` pair
 
@@ -788,7 +788,7 @@ If the `options` parameter is an `object` that contains the following set of par
 
 | option name | value type | default value | description |
 |:---|---|---:|:---|
-| `defaultItem` | `string` | --- | if set it defines a name of the item used by default |
+| `defaultItem` | `string` | --- | (*deprecated **since `v0.0.26`***) if set it defines a name of the item used by default |
 | `useClear` | `boolean` | `true` | if set to `true`, before the load of the items, the list is cleared |
 | `force` | `boolean` | `false` | if set to `true`, the item which is already present will be replaced with a new one |
 

package/doc/html-helper-lib.md

@@ -1,6 +1,6 @@
->|***rev.*:**|0.1.15|
+>|***rev.*:**|0.1.16|
 >|:---|---:|
->|date:|2025-03-29|
+>|date:|2025-08-27|
 
 ## Introduction
 
@@ -33,6 +33,15 @@ This function checks whether or not a given object represents an HTML-element an
 |:---|---|---:|:---|
 | `obj` | `any` | --- | some element to be checked |
 
+<a name="isHTMLButton"></a>
+#### **isHTMLButton(obj)** => `boolean`
+
+This function checks whether or not a given object represents an HTML-button element and if so returns `true` or `false` if else.
+
+| parameter name | value type | default value | description |
+|:---|---|---:|:---|
+| `obj` | `any` | --- | some element to be checked |
+
 <a name="isSelectedHTMLElement"></a>
 #### **isSelectedHTMLElement(obj)** => `boolean`
 

package/index.js

@@ -1,4 +1,4 @@
-// [v0.1.027-20250329]
+// [v0.1.029-20250827]
 
 // === module init block ===
 
@@ -27,6 +27,7 @@ const components = {
 
 const eventHelper = {
   pushEventHandler: ev_helper.pushEventHandler,
+  removeEventHandler: ev_helper.removeEventHandler,
   triggerEventHandler: ev_helper.triggerEventHandler,
 };
 
@@ -70,8 +71,8 @@ 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.isHTMLButton = html_bts.isHTMLButton;
 
 module.exports.THtmlInputField = html_flds.THtmlInputField;
 

package/lib/event-hfunc.js

@@ -1,4 +1,4 @@
-// [v0.1.062-20241115]
+// [v0.1.063-20250503]
 
 // === module init block ===
 
@@ -16,13 +16,13 @@
 
 /**
  * @function pushEventHandler
- * @param {object} pool - pool object
+ * @param {Map<string, Function>} pool - pool object
  * @param {string} name - event name
- * @param {func} evnt - callback function
+ * @param {Function} evnt - callback function
  * @returns {void}
  * @inner
  */
-function pushEventHandler(pool, name, evnt){
+function pushEventHandler(pool, name, evnt) {
   const _name = typeof name === 'string' ? name.trim() : '';
   if (_name !== '' && typeof evnt === 'function') {
     if (!pool.has(_name)) {
@@ -35,15 +35,32 @@ function pushEventHandler(pool, name, evnt){
   };
 };
 
+/**
+ * @function removeEventHandler
+ * @param {Map<string, Function>} pool - pool object
+ * @param {string} name - event name
+ * @returns {void}
+ * @inner
+ */
+function removeEventHandler(pool, name) {
+  const key = typeof name === 'string' ? name.trim() : '';
+  if (key !== '') {
+    /* NOTE:
+    *    for current you can't reset or set new one on the same event
+    */
+    if (pool.has(key)) pool.delete(key);
+  };
+};
+
 /**
  * @function triggerEventHandler
- * @param {object} pool - pool object
+ * @param {Map<string, Function>} pool - pool object
  * @param {string} name - event name
  * @param {...any} [args]
  * @returns {void}
  * @inner
  */
-function triggerEventHandler(pool, name, ...args){
+function triggerEventHandler(pool, name, ...args) {
   const _name = typeof name === 'string' ? name.trim() : '';
   if (_name !== '') {
     if (pool.has(_name)) pool.get(_name)(...args);
@@ -56,5 +73,6 @@ function triggerEventHandler(pool, name, ...args){
 
 // === module exports block ===
 
-exports.pushEventHandler = pushEventHandler;
-exports.triggerEventHandler = triggerEventHandler;
+module.exports.pushEventHandler = pushEventHandler;
+module.exports.triggerEventHandler = triggerEventHandler;
+module.exports.removeEventHandler = removeEventHandler;

package/lib/html-ctrls/buttons.js

@@ -1,19 +1,18 @@
-// [v0.1.058-20250416]
+// [v0.1.064-20250827]
 
 // === module init block ===
 
 const {
   isNotEmptyString,
   isPlainObject, valueToArray,
-  //TItemsICollection,
 } = require('@ygracs/bsfoc-lib-js');
 
 const {
   TItemsICollection,
-} = require('@ygracs/bsfoc-lib-js');
+} = require('@ygracs/lists-lib-js');
 
 const {
-  isHTMLElement,
+  isHTMLElement, isHTMLButton,
   valueToIDString,
   lockHTMLElement, unlockHTMLElement,
   CSS_CLASS_STRING,
@@ -25,15 +24,9 @@ const {
 } = require('./mod-hfunc.js');
 
 const {
-  //CSS_CLASS_SELECTED,
   CSS_CLASS_DISABLED,
-  //CSS_CLASS_HIDDEN,
 } = CSS_CLASS_STRING;
 
-const etlHTagInputForBtn = new Set([
-  'button', 'submit', 'reset', 'image',
-]);
-
 // === module extra block (helper functions) ===
 
 // === module main block ===
@@ -48,32 +41,6 @@ const BTS_DEF_GROUP_NAME = 'all';
  * (* function definitions *)
  */
 
-/**
- * @function isHTMLButton
- * @param {any} obj - element to be verified
- * @returns {boolean}
- * @description Checks if the given object is an HTML-button.
- */
-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: {
-        break;
-      }
-    };
-  };
-  return result;
-}
-
 /***
  * (* class definitions *)
  */
@@ -86,7 +53,7 @@ class THtmlButtonsSet {
   #_btnCol;
 
   /**
-   * @description Creates an instance of a buttons set
+   * Creates an instance of a buttons set
    */
   constructor() {
     // define default functions for manipulators
@@ -127,133 +94,133 @@ class THtmlButtonsSet {
   }
 
   /**
+   * Checks whether a target item with a given name exists.
    * @param {string} name - element name
    * @returns {boolean}
    * @see TItemsICollection.hasItem
-   * @description Checks whether a target item with a given name exists.
    */
   hasItem(name) {
     return this.#_btnCol.hasItem(name);
   }
 
   /**
+   * Adds buttons to a set members.
    * @param {string} name - element name
    * @param {any} item - element
    * @param {...string} [group] - name of a target groups
    * @returns {boolean}
    * @see TItemsICollection.addItem
-   * @description Adds buttons to a set members.
    */
   addItem(...args) {
     return this.#_btnCol.addItem(...args);
   }
 
   /**
+   * Adds button to a listed groups.
    * @param {string} name - element name
    * @param {...string} [group] - name of a target groups
    * @returns {boolean}
    * @see TItemsICollection.addItemToCategory
-   * @description Adds button to a listed groups.
    */
   addItemToGroup(...args) {
     return this.#_btnCol.addItemToCategory(...args);
   }
 
   /**
+   * Deletes button from a set members.
    * @param {string} name - element name
    * @returns {boolean}
    * @see TItemsICollection.delItem
-   * @description Deletes button from a set members.
    */
   delItem(name) {
     return this.#_btnCol.delItem(name);
   }
 
   /**
+   * Deletes button from a listed groups.
    * @param {string} name - element name
    * @param {...string} [group] - name of a target groups
    * @returns {boolean}
    * @see TItemsICollection.delItemFromGroup
-   * @description Deletes button from a listed groups.
    */
   delItemFromGroup(...args) {
     return this.#_btnCol.delItemFromGroup(...args);
   }
 
   /**
+   * Renames button in a set.
    * @param {string} name - old name
    * @param {string} value - new name
    * @returns {boolean}
    * @see TItemsICollection.renameItem
-   * @description Renames button in a set.
    */
   renameItem(name, value) {
     return this.#_btnCol.renameItem(name, value, false);
   }
 
   /**
+   * Tries to enable button.
    * @param {string} name - element name
    * @returns {void}
-   * @description Tries to enable button.
    */
   enableItem(name) {
     unlockHTMLElement(this.#_btnCol.getItem(name));
   }
 
   /**
+   * Tries to disable button.
    * @param {string} name - element name
    * @returns {void}
-   * @description Tries to disable button.
    */
   disableItem(name) {
     lockHTMLElement(this.#_btnCol.getItem(name));
   }
 
   /**
+   * Checks whether a target group with a given name exists.
    * @param {string} name - group name
    * @returns {boolean}
    * @see TItemsICollection.hasCategory
-   * @description Checks whether a target group with a given name exists.
    */
   hasGroup(name) {
     return this.#_btnCol.hasCategory(name);
   }
 
   /**
+   * Adds a group with a given name.
    * @param {string} name - group name
    * @returns {boolean}
    * @see TItemsICollection.addCategory
-   * @description Adds a group with a given name.
    */
   addGroup(name) {
     return this.#_btnCol.addCategory(name);
   }
 
   /**
+   * Deletes a group with a given name.
    * @param {string} name - group name
    * @returns {boolean}
    * @see TItemsICollection.delCategory
-   * @description Deletes a group with a given name.
    */
   delGroup(name) {
     return this.#_btnCol.delCategory(name);
   }
 
   /**
+   * Renames group in a set.
    * @param {string} name - old name
    * @param {string} value - new name
    * @returns {boolean}
    * @see TItemsICollection.renameCategory
-   * @description Renames group in a set.
    */
   renameGroup(name, value) {
     return this.#_btnCol.renameCategory(name, value, false);
   }
 
   /**
+   * Enables all buttons in a given group.
    * @param {string} value - group name
    * @returns {void}
-   * @description Enables all buttons in a given group.
    */
   enableGroup(value) {
     const group = this.#_btnCol.getCategory(value);
@@ -261,9 +228,9 @@ class THtmlButtonsSet {
   }
 
   /**
+   * Disables all buttons in a given group.
    * @param {string} value - group name
    * @returns {void}
-   * @description Disables all buttons in a given group.
    */
   disableGroup(value) {
     const group = this.#_btnCol.getCategory(value);
@@ -281,6 +248,14 @@ class THtmlButtonsSet {
 
 };
 
+/**
+ * A description for ARC-buttons set.
+ * @typedef {Object} arcButtonsDesc
+ * @property {?HTMLElement} btnApply - button 'apply'
+ * @property {?HTMLElement} btnReset - button 'reset'
+ * @property {?HTMLElement} btnCancel - button 'cancel'
+ */
+
 /**
  * @classdesc This class implements an interface of a pre-defined buttons set.
  *            A set provide a three button: <apply>, <reset> and <cancel>.
@@ -292,27 +267,17 @@ class THtmlButtonsControllerARCSet {
   #_events;
 
   /**
-   * @typedef {Object} arcButtonsDesc
-   * @property {?HTMLElement} btnApply - button 'apply'
-   * @property {?HTMLElement} btnReset - button 'reset'
-   * @property {?HTMLElement} btnCancel - button 'cancel'
-   * @description A description for ARC-buttons set.
-   */
-
-  /**
+   * Creates an instance of the buttons set.
    * @param {arcButtonsDesc} opt - an option
-   * @description Creates an instance of the buttons set.
    */
   constructor(opt) {
-    // load options
-    const _options = isPlainObject(opt) ? opt : {};
     // load controls
     /** @type {arcButtonsDesc} */
     let {
       btnApply,
       btnReset,
       btnCancel,
-    } = _options;
+    } = isPlainObject(opt) ? opt : {};
     if (!isHTMLButton(btnApply)) btnApply = null;
     if (!isHTMLButton(btnReset)) btnReset = null;
     if (!isHTMLButton(btnCancel)) btnCancel = null;
@@ -369,42 +334,42 @@ class THtmlButtonsControllerARCSet {
   }
 
   /**
+   * Disables all buttons in 'main' group.
    * @returns {void}
-   * @description Disables all buttons in 'main' group.
    */
   disableMain() {
     this.#_btnSet.disableGroup('main');
   }
 
   /**
+   * Enables all buttons in 'main' group.
    * @returns {void}
-   * @description Enables all buttons in 'main' group.
    */
   enableMain() {
     this.#_btnSet.enableGroup('main');
   }
 
   /**
+   * Disables all buttons.
    * @returns {void}
-   * @description Disables all buttons.
    */
   disableAll() {
     this.#_btnSet.disableGroup('all');
   }
 
   /**
+   * Enables all buttons.
    * @returns {void}
-   * @description Enables all buttons.
    */
   enableAll() {
     this.#_btnSet.enableGroup('all');
   }
 
   /**
+   * Sets a callback function to handle event.
    * @param {string} name - event name
    * @param {func} evnt - a callback function
    * @returns {void}
-   * @description Sets a callback function to handle event.
    */
   on(name, evnt) {
     pushEventHandler(this.#_events, name, evnt);
@@ -413,9 +378,9 @@ class THtmlButtonsControllerARCSet {
 
 // === module exports block ===
 
-exports.THtmlButtonsSet = THtmlButtonsSet;
-exports.THtmlButtonsControllerARCSet = THtmlButtonsControllerARCSet;
+module.exports.THtmlButtonsSet = THtmlButtonsSet;
+module.exports.THtmlButtonsControllerARCSet = THtmlButtonsControllerARCSet;
 
-exports.BTS_DEF_GROUP_NAME = BTS_DEF_GROUP_NAME;
+module.exports.BTS_DEF_GROUP_NAME = BTS_DEF_GROUP_NAME;
 
-exports.isHTMLButton = isHTMLButton;
+module.exports.isHTMLButton = isHTMLButton;