@cntwg/html-helper 0.0.24 → 0.0.26

package/CHANGELOG.md

@@ -1,3 +1,23 @@
+#### *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.
+
+> - update dependency on `@ygracs/bsfoc-lib-js` module to v0.2.3;
+> - add dependency on `@ygracs/lists-lib-js` module;
+> - remove some deprecates (*see docs for details*);
+> - change pattern for an element manipulation functions (*see docs for details*);
+> - change behavior for `loadItems` method of `THtmlStubItemsSet` class in handling `options` parameter (*see docs for details*).
+
 #### *v0.0.24*
 
 Pre-release version.

package/doc/html-ctrls-list.md

@@ -1,6 +1,6 @@
->|***rev.*:**|0.1.22|
+>|***rev.*:**|0.1.24|
 >|:---|---:|
->|date:|2024-11-13|
+>|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,25 +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 |
 
-If the `list` parameter is an `object` that contains the following set of values:
+> \[!] NOTE: *`[since v0.0.25]`* the use of a booleans as an `options` value is deprecated and will be dropped soon.
+
+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
 
@@ -786,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.14|
+>|***rev.*:**|0.1.15|
 >|:---|---:|
->|date:|2024-11-10|
+>|date:|2025-03-29|
 
 ## Introduction
 
@@ -170,7 +170,7 @@ This function enables a given HTML-element.
 | `obj` | `HTMLElement` | --- | some element to be modified |
 
 <a name="activateHTMLElements"></a>
-#### **activateHtmlElements(arg_1\[, arg_2\[, ...arg_N]])** => `void`
+#### **activateHTMLElements(arg_1\[, arg_2\[, ...arg_N]])** => `void`
 
 This function enables all HTML-elements received as a function arguments.
 
@@ -207,8 +207,8 @@ The `options` parameter if sets to `true` force the function to remove all dupli
 
 > Note: Purpose of those functions will be discussed and some may be deprecate and make obsolete or functionality may be altered. So use it with cautions in mind.
 
-<a name="createNewHtmlElement"></a>
-#### **createNewHtmlElement(tagName\[, options])**
+<a name="createNewHTMLElement"></a>
+#### **createNewHTMLElement(tagName\[, options])**
 
 This function helps to simplify the process of creating a new HTML-element. It receives the tag name (`tagName` parameter) and the options as a second parameter:
 

package/index.js

@@ -1,4 +1,4 @@
-// [v0.1.025-20241115]
+// [v0.1.028-20250503]
 
 // === module init block ===
 
@@ -27,6 +27,7 @@ const components = {
 
 const eventHelper = {
   pushEventHandler: ev_helper.pushEventHandler,
+  removeEventHandler: ev_helper.removeEventHandler,
   triggerEventHandler: ev_helper.triggerEventHandler,
 };
 
@@ -69,7 +70,7 @@ 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.createNewHTMLElement = html_helper.createNewHTMLElement;
 
 module.exports.isHTMLButton = html_bts.isHTMLButton;
 
@@ -85,15 +86,4 @@ module.exports.classes = components;
 
 // deprecated
 module.exports.component = components;
-module.exports.hideHtmlElement = html_helper.hideHtmlElement;
-module.exports.showHtmlElement = html_helper.showHtmlElement;
-module.exports.selectHtmlElement = html_helper.selectHtmlElement;
-module.exports.unselectHtmlElement = html_helper.unselectHtmlElement;
-module.exports.markHtmlElementAsCurrent = html_helper.markHtmlElementAsCurrent;
-module.exports.unmarkCurrentHtmlElement = html_helper.unmarkCurrentHtmlElement;
-module.exports.markHtmlElementAsActive = html_helper.markHtmlElementAsActive;
-module.exports.unmarkActiveHtmlElement = html_helper.unmarkActiveHtmlElement;
-module.exports.lockHtmlElement = html_helper.lockHtmlElement;
-module.exports.unlockHtmlElement = html_helper.unlockHtmlElement;
-module.exports.inactivateHtmlElements = html_helper.inactivateHtmlElements;
-module.exports.activateHtmlElements = html_helper.activateHtmlElements;
+module.exports.createNewHtmlElement = html_helper.createNewHtmlElement;

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,13 +1,16 @@
-// [v0.1.056-20241119]
+// [v0.1.062-20250509]
 
 // === module init block ===
 
 const {
   isNotEmptyString,
   isPlainObject, valueToArray,
-  TItemsICollection,
 } = require('@ygracs/bsfoc-lib-js');
 
+const {
+  TItemsICollection,
+} = require('@ygracs/lists-lib-js');
+
 const {
   isHTMLElement,
   valueToIDString,
@@ -21,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 ===
@@ -40,6 +37,10 @@ const etlHTagInputForBtn = new Set([
 
 const BTS_DEF_GROUP_NAME = 'all';
 
+const etlHTagInputForBtn = new Set([
+  'button', 'submit', 'reset', 'image',
+]);
+
 /***
  * (* function definitions *)
  */
@@ -62,9 +63,7 @@ function isHTMLButton(obj) {
         result = etlHTagInputForBtn.has(obj.type.toLowerCase());
         break;
       }
-      default: {
-        break;
-      }
+      default: {}
     };
   };
   return result;
@@ -78,7 +77,7 @@ function isHTMLButton(obj) {
  * @classdesc This class implements an interface of a buttons set
  */
 class THtmlButtonsSet {
-  /** @property {TItemsICollection} */
+  /** @type {TItemsICollection} */
   #_btnCol;
 
   /**
@@ -103,20 +102,20 @@ class THtmlButtonsSet {
   }
 
   /**
-   * @property {string[]}
+   * Contains a list of an element names
+   * @type {string[]}
    * @readonly
    * @see TItemsICollection.ItemNames
-   * @description Contains a list of an element names
    */
   get ItemNames() {
     return this.#_btnCol.ItemNames;
   }
 
   /**
-   * @property {string[]}
+   * Contains a list of an elements group names
+   * @type {string[]}
    * @readonly
    * @see TItemsICollection.CategoryNames
-   * @description Contains a list of an elements group names
    */
   get GroupNames() {
     return this.#_btnCol.CategoryNames;
@@ -267,9 +266,9 @@ class THtmlButtonsSet {
   }
 
   /**
-   * @returns {function}
+   * Returns a function wich do a validation check.
+   * @type {isHTMLButton}
    * @static
-   * @description Returns a function wich do a validation check.
    */
   static get isHTMLButton() {
     return isHTMLButton;
@@ -282,9 +281,9 @@ class THtmlButtonsSet {
  *            A set provide a three button: <apply>, <reset> and <cancel>.
  */
 class THtmlButtonsControllerARCSet {
-  /** @property {THtmlButtonsSet} */
+  /** @type {THtmlButtonsSet} */
   #_btnSet;
-  /** @property {Map} */
+  /** @type {Map<string, Function>} */
   #_events;
 
   /**
@@ -300,15 +299,13 @@ class THtmlButtonsControllerARCSet {
    * @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;
@@ -409,9 +406,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;

package/lib/html-ctrls/fields.js

@@ -1,4 +1,4 @@
-// [v0.1.017-20241119]
+// [v0.1.022-20250509]
 
 // === module init block ===
 
@@ -9,7 +9,7 @@ const {
 } = require('@ygracs/bsfoc-lib-js');
 
 const {
-  isHTMLElement, createNewHtmlElement,
+  isHTMLElement, createNewHTMLElement,
   valueToIDString, valueToClassList,
   readAsAttrValue,
   showHTMLElement, hideHTMLElement,
@@ -29,14 +29,14 @@ const lpAllowedValues = new Map([
 
 /**
  * @typedef {Object} ifcTypeDesc
- * @property {string} type - type
- * @property {string} subtype - subtype
+ * @property {string} type - field general type
+ * @property {string} subtype - field sub-type
  * @description An input field type description
  */
 
 /**
  * @function getInputFieldTypeDescr
- * @param {string} value
+ * @param {string} value - field type
  * @returns {ifcTypeDesc}
  * @inner
  * @description Returns field description by a given type.
@@ -70,13 +70,13 @@ function getInputFieldTypeDescr(value) {
 
 /**
  * @function getLabelPositionID
- * @param {string} value
+ * @param {string} value - label position identifier
  * @returns {number}
  * @inner
  * @description Returns label position ID by its name.
  */
 function getLabelPositionID(value) {
-  let key = readAsString(value, true);
+  let key = readAsString(value, { useTrim: true });
   if (!lpAllowedValues.has(key)) key = 'default';
   return lpAllowedValues.get(key);
 };
@@ -95,51 +95,70 @@ function getLabelPositionID(value) {
  * (* class definitions *)
  */
 
+/**
+ * @typedef {Object} OPT_ifcdesc
+ * @property {HTMLElement} [host] - host element
+ * @property {string} [idPref]
+ * @property {string} [label] - text of a label
+ * @property {object} [labelPosition]
+ * @property {boolean} [useDelim]
+ * @property {object} [baseClassID]
+ * @property {string} [hint] - hint to show when empty
+ * @property {string} [type] - field type
+ * @property {boolean} [readonly] - mode flag
+ * @description An options set for create ifc
+ */
+
+/**
+ * @typedef {Object} OPT_ifcsett
+ * @property {string} [idPref]
+ * @property {(string|string[])} [baseClassID]
+ * @property {string} [hint] - hint to show when empty
+ * @property {string} [type] - field type
+ * @property {boolean} [readonly=true] - mode flag
+ * @description An options set for `THtmlInputField`-class
+ */
+
+/**
+ * @typedef {Object} ifcElementsDesc
+ * @property {HTMLElement} host - host element
+ * @property {HTMLElement} label - label element
+ * @property {HTMLElement} field - field element
+ * @description A description for input field elements set.
+ */
+
 /**
  * @classdesc This class implements an interface of an input field element
  */
 class THtmlInputField {
-  /** @property {?HTMLElement} */
+  /** @type {?HTMLElement} */
   #_host;// = null;
-  /** @property {?HTMLElement} */
+  /** @type {?HTMLElement} */
   #_label;// = null;
-  /** @property {?HTMLElement} */
+  /** @type {?HTMLElement} */
   #_field;// = null;
   #_id = '';
   #_value = '';
-  /** @property {object} */
+  /** @type {OPT_ifcsett} */
   #_options = null;
   /**
    * @typedef {Object} statIFCtrl
-   * @property {string} fldType
-   * @property {string} fldSubType
-   * @property {boolean} isReadOnly
-   * @property {boolean} isModified
+   * @property {string} fldType - field general type
+   * @property {string} fldSubType - field sub-type
+   * @property {boolean} isReadOnly - mode flag
+   * @property {boolean} isModified - indicates whether any changes was made
    * @inner
    * @description A controller status
    */
-  /** @property {statIFCtrl} */
+  /** @type {statIFCtrl} */
   #_status;// = null;
-  /** @property {Map} */
+  /** @type {Map<string, Function>} */
   #_events;// = null;
 
-  /**
-   * @typedef {Object} ifcElementsDesc
-   * @property {HTMLElement} host - host element
-   * @property {HTMLElement} label - label element
-   * @property {HTMLElement} field - field element
-   * @description A description for input field elements set.
-   */
-
   /**
    * @param {string} name - <*reserved*>
    * @param {ifcElementsDesc} eholds - elements set
-   * @param {object} [opt]
-   * @param {string} [opt.idPref]
-   * @param {(string|string[])} [opt.baseClassID]
-   * @param {string} [opt.hint]
-   * @param {string} [opt.type]
-   * @param {boolean} [opt.readonly=true]
+   * @param {OPT_ifcsett} [opt] - options
    * @description Creates an instance of an input field element
    */
   constructor(name, eholds, opt) {
@@ -185,28 +204,28 @@ class THtmlInputField {
   }
 
   /**
-   * @property {boolean}
+   * Indicates whether element value was modified.
+   * @type {boolean}
    * @readonly
-   * @description Indicates whether element value was modified.
    */
   get isModified() {
     return this.#_status.isModified;
   }
 
   /**
+   * Returns an input element origin type.
    * @since v0.0.23
-   * @property {string}
+   * @type {string}
    * @readonly
-   * @description Returns an input element origin type.
    */
   get type() {
     return this.#_status.fldType;
   }
 
   /**
-   * @property {string}
+   * Containes an element value.
+   * @type {string}
    * @fires THtmlInputField#value-empty
-   * @description Containes an element value.
    */
   get value() {
     const field = this.#_field;
@@ -252,7 +271,7 @@ class THtmlInputField {
   };
 
   /**
-   * @param {object} e
+   * @param {object} e - event
    * @returns {void}
    * @private
    * @fires THtmlInputField#value-changed
@@ -275,7 +294,7 @@ class THtmlInputField {
   };
 
   /**
-   * @param {object} e
+   * @param {object} e - event
    * @returns {void}
    * @private
    * @fires THtmlInputField#value-empty
@@ -301,7 +320,7 @@ class THtmlInputField {
   };
 
   /**
-   * @param {object} e
+   * @param {object} e - event
    * @returns {void}
    * @private
    */
@@ -371,10 +390,10 @@ class THtmlInputField {
 
   /**
    * @param {string} name - <*reserved*>
-   * @param {object} opt
+   * @param {OPT_ifcdesc} opt - options
    * @returns {?THtmlInputField}
    * @static
-   * @description Creates a new element.
+   * @description Creates a new instance.
    */
   static create(name, opt) {
     const eholds = THtmlInputField.createElement(name, opt, true);
@@ -388,17 +407,8 @@ class THtmlInputField {
 
   /**
    * @param {string} name
-   * @param {object} [opt]
-   * @param {object} [opt.host]
-   * @param {string} [opt.idPref]
-   * @param {object} [opt.label]
-   * @param {object} [opt.labelPosition]
-   * @param {boolean} [opt.useDelim]
-   * @param {object} [opt.baseClassID]
-   * @param {string} [opt.hint]
-   * @param {object} [opt.type]
-   * @param {boolean} [opt.readonly]
-   * @param {boolean} [doRetChild=false]
+   * @param {OPT_ifcdesc} [opt] - options
+   * @param {boolean} [doRetChild=false] - mode flag
    * @returns {(HTMLElement|ifcElementsDesc)}
    * @static
    * @description Creates a new elements.
@@ -407,6 +417,7 @@ class THtmlInputField {
     const id = valueToIDString(name);
     const _options = isPlainObject(opt) ? opt : {};
     let fldSubType = '';
+    /** @type {OPT_ifcdesc} */
     let {
       host,
       idPref,
@@ -430,18 +441,18 @@ class THtmlInputField {
     bcidLabel = valueToClassList(bcidLabel);
     bcidField = valueToClassList(bcidField);
     idPref = valueToIDString(idPref);
-    hint = readAsString(hint, true);
+    hint = readAsString(hint, { useTrim: true });
     ({ type: fldType, subtype: fldSubType } = getInputFieldTypeDescr(fldType));
     if (fldSubType === 'switch') bcidField.push('switch');
     labelPosition = getLabelPositionID(labelPosition);
     if (typeof useDelim !== 'boolean') useDelim = true;
-    label = readAsString(label, true);
+    label = readAsString(label, { useTrim: true });
     if (label !== '') label = `${label}${useDelim ? ':' : ''}`;
     isReadOnly = readAsBool(isReadOnly, true);
     let fldID = idPref === '' ? id : `${idPref}-${id}`;
     if (!isHTMLElement(host)) {
-      host = createNewHtmlElement('div', {
-        class: bcidHost,
+      host = createNewHTMLElement('div', {
+        classNames: bcidHost,
       });
     };
     let lblHolder = null;
@@ -450,23 +461,23 @@ class THtmlInputField {
     if (host) {
       lblHolder = host.querySelector(`label[for="${fldID}"]`);
       if (!lblHolder) {
-        lblHolder = createNewHtmlElement('label', {
+        lblHolder = createNewHTMLElement('label', {
           text: label,
           attr: {
             for: fldID,
           },
-          class: bcidLabel,
+          classNames: bcidLabel,
         });
       };
       fldHolder = host.querySelector(`input#${fldID}`);
       if (!fldHolder) {
-        fldHolder = createNewHtmlElement('input', {
+        fldHolder = createNewHTMLElement('input', {
           id: fldID,
           attr: {
             type: fldType,
             placeholder: hint,
           },
-          class: bcidField,
+          classNames: bcidField,
         });
       };
       if (fldHolder) {