@cntwg/html-helper 0.0.22 → 0.0.23

package/lib/html-ctrls/buttons.js

@@ -1,4 +1,4 @@
-// [v0.1.050-20240705]
+// [v0.1.056-20241119]
 
 // === module init block ===
 
@@ -11,7 +11,7 @@ const {
 const {
   isHTMLElement,
   valueToIDString,
-  lockHtmlElement, unlockHtmlElement,
+  lockHTMLElement, unlockHTMLElement,
   CSS_CLASS_STRING,
 } = require('../html-helper-lib.js');
 
@@ -26,15 +26,31 @@ const {
   //CSS_CLASS_HIDDEN,
 } = CSS_CLASS_STRING;
 
-const BTS_DEF_GROUP_NAME = 'all';
-
 const etlHTagInputForBtn = new Set([
   'button', 'submit', 'reset', 'image',
 ]);
 
 // === module extra block (helper functions) ===
 
-function isHTMLButton(obj){
+// === module main block ===
+
+/***
+ * (* constant definitions *)
+ */
+
+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()) {
@@ -54,30 +70,21 @@ function isHTMLButton(obj){
   return result;
 }
 
-// === module main block ===
-
-/***
- * (* constant definitions *)
- */
-
-/***
- * (* function definitions *)
- */
-
 /***
  * (* class definitions *)
  */
 
 /**
- * @description This class implements an instance of a buttons set
+ * @classdesc This class implements an interface of a buttons set
  */
 class THtmlButtonsSet {
-  #_btnCol = null;
+  /** @property {TItemsICollection} */
+  #_btnCol;
 
   /**
-   * @param {none}
+   * @description Creates an instance of a buttons set
    */
-  constructor(){
+  constructor() {
     // define default functions for manipulators
     const __user_index_getter = (value) => {
       return valueToIDString(value);
@@ -96,153 +103,167 @@ class THtmlButtonsSet {
   }
 
   /**
-   * @property {array}
+   * @property {string[]}
    * @readonly
    * @see TItemsICollection.ItemNames
+   * @description Contains a list of an element names
    */
-  get ItemNames(){
+  get ItemNames() {
     return this.#_btnCol.ItemNames;
   }
 
   /**
-   * @property {array}
+   * @property {string[]}
    * @readonly
    * @see TItemsICollection.CategoryNames
+   * @description Contains a list of an elements group names
    */
-  get GroupNames(){
+  get GroupNames() {
     return this.#_btnCol.CategoryNames;
   }
 
   /**
-   * @param {ID_STRING}
-   * @returns {bool}
+   * @param {string} name - element name
+   * @returns {boolean}
    * @see TItemsICollection.hasItem
    * @description Checks whether a target item with a given name exists.
    */
-  hasItem(name){
+  hasItem(name) {
     return this.#_btnCol.hasItem(name);
   }
 
   /**
+   * @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){
+  addItem(...args) {
     return this.#_btnCol.addItem(...args);
   }
 
   /**
+   * @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){
+  addItemToGroup(...args) {
     return this.#_btnCol.addItemToCategory(...args);
   }
 
   /**
-   * @param {ID_STRING}
+   * @param {string} name - element name
+   * @returns {boolean}
    * @see TItemsICollection.delItem
    * @description Deletes button from a set members.
    */
-  delItem(name){
+  delItem(name) {
     return this.#_btnCol.delItem(name);
   }
 
   /**
+   * @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){
+  delItemFromGroup(...args) {
     return this.#_btnCol.delItemFromGroup(...args);
   }
 
   /**
-   * @param {ID_STRING} - old name
-   * @param {ID_STRING} - new name
+   * @param {string} name - old name
+   * @param {string} value - new name
+   * @returns {boolean}
    * @see TItemsICollection.renameItem
    * @description Renames button in a set.
    */
-  renameItem(oldName, newName){
-    return this.#_btnCol.renameItem(oldName, newName, false);
+  renameItem(name, value) {
+    return this.#_btnCol.renameItem(name, value, false);
   }
 
   /**
-   * @param {ID_STRING}
-   * @returns {none}
+   * @param {string} name - element name
+   * @returns {void}
    * @description Tries to enable button.
    */
-  enableItem(name){
-    unlockHtmlElement(this.#_btnCol.getItem(name));
+  enableItem(name) {
+    unlockHTMLElement(this.#_btnCol.getItem(name));
   }
 
   /**
-   * @param {ID_STRING}
-   * @returns {none}
+   * @param {string} name - element name
+   * @returns {void}
    * @description Tries to disable button.
    */
-  disableItem(name){
-    lockHtmlElement(this.#_btnCol.getItem(name));
+  disableItem(name) {
+    lockHTMLElement(this.#_btnCol.getItem(name));
   }
 
   /**
-   * @param {ID_STRING}
-   * @returns {bool}
+   * @param {string} name - group name
+   * @returns {boolean}
    * @see TItemsICollection.hasCategory
    * @description Checks whether a target group with a given name exists.
    */
-  hasGroup(name){
+  hasGroup(name) {
     return this.#_btnCol.hasCategory(name);
   }
 
   /**
-   * @param {ID_STRING}
-   * @returns {bool}
+   * @param {string} name - group name
+   * @returns {boolean}
    * @see TItemsICollection.addCategory
    * @description Adds a group with a given name.
    */
-  addGroup(name){
+  addGroup(name) {
     return this.#_btnCol.addCategory(name);
   }
 
   /**
-   * @param {ID_STRING}
-   * @returns {bool}
+   * @param {string} name - group name
+   * @returns {boolean}
    * @see TItemsICollection.delCategory
    * @description Deletes a group with a given name.
    */
-  delGroup(name){
+  delGroup(name) {
     return this.#_btnCol.delCategory(name);
   }
 
   /**
-   * @param {ID_STRING} - old name
-   * @param {ID_STRING} - new name
-   * @returns {bool}
+   * @param {string} name - old name
+   * @param {string} value - new name
+   * @returns {boolean}
    * @see TItemsICollection.renameCategory
    * @description Renames group in a set.
    */
-  renameGroup(oldName, newName){
-    return this.#_btnCol.renameCategory(oldName, newName, false);
+  renameGroup(name, value) {
+    return this.#_btnCol.renameCategory(name, value, false);
   }
 
   /**
-   * @param {ID_STRING}
-   * @returns {none}
+   * @param {string} value - group name
+   * @returns {void}
    * @description Enables all buttons in a given group.
    */
-  enableGroup(value){
+  enableGroup(value) {
     const group = this.#_btnCol.getCategory(value);
-    valueToArray(group).forEach(item => unlockHtmlElement(item));
+    valueToArray(group).forEach(item => unlockHTMLElement(item));
   }
 
   /**
-   * @param {ID_STRING}
-   * @returns {none}
+   * @param {string} value - group name
+   * @returns {void}
    * @description Disables all buttons in a given group.
    */
-  disableGroup(value){
+  disableGroup(value) {
     const group = this.#_btnCol.getCategory(value);
-    valueToArray(group).forEach(item => lockHtmlElement(item));
+    valueToArray(group).forEach(item => lockHTMLElement(item));
   }
 
   /**
@@ -250,30 +271,39 @@ class THtmlButtonsSet {
    * @static
    * @description Returns a function wich do a validation check.
    */
-  static get isHTMLButton(){
+  static get isHTMLButton() {
     return isHTMLButton;
   }
 
 };
 
 /**
- * @description This class implements an instance of a pre-defined buttons set.
- *              A set provide a three button: <apply>, <reset> and <cancel>.
+ * @classdesc This class implements an interface of a pre-defined buttons set.
+ *            A set provide a three button: <apply>, <reset> and <cancel>.
  */
 class THtmlButtonsControllerARCSet {
-  #_btnSet = null;
-  #_events = null;
+  /** @property {THtmlButtonsSet} */
+  #_btnSet;
+  /** @property {Map} */
+  #_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.
+   */
 
   /**
-   * @param {object} opt
-   * @param {HTMLElement} opt.btnApply
-   * @param {HTMLElement} opt.btnReset
-   * @param {HTMLElement} opt.btnCancel
+   * @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,
@@ -282,11 +312,6 @@ class THtmlButtonsControllerARCSet {
     if (!isHTMLButton(btnApply)) btnApply = null;
     if (!isHTMLButton(btnReset)) btnReset = null;
     if (!isHTMLButton(btnCancel)) btnCancel = null;
-    /*const controls = {
-      btnApply,
-      btnReset,
-      btnCancel,
-    };*/ // // TODO:  ???
     // init buttons set
     const _btnSet = new THtmlButtonsSet();
     this.#_btnSet = _btnSet;
@@ -310,9 +335,9 @@ class THtmlButtonsControllerARCSet {
   }
 
   /**
-   * @param {object}
-   * @param {ID_STRING}
-   * @returns {none}
+   * @param {object} e - event
+   * @param {string} key - button ID
+   * @returns {void}
    * @private
    */
   #_on_btn_pressed = (e, key) => {
@@ -329,9 +354,9 @@ class THtmlButtonsControllerARCSet {
   }
 
   /**
-   * @param {ID_STRING}
-   * @param {...any}
-   * @returns {none}
+   * @param {string} name - event name
+   * @param {...any} args
+   * @returns {void}
    * @private
    * @see triggerEventHandler
    */
@@ -340,48 +365,44 @@ class THtmlButtonsControllerARCSet {
   }
 
   /**
-   * @param {none}
-   * @returns {none}
+   * @returns {void}
    * @description Disables all buttons in 'main' group.
    */
-  disableMain(){
+  disableMain() {
     this.#_btnSet.disableGroup('main');
   }
 
   /**
-   * @param {none}
-   * @returns {none}
+   * @returns {void}
    * @description Enables all buttons in 'main' group.
    */
-  enableMain(){
+  enableMain() {
     this.#_btnSet.enableGroup('main');
   }
 
   /**
-   * @param {none}
-   * @returns {none}
+   * @returns {void}
    * @description Disables all buttons.
    */
-  disableAll(){
+  disableAll() {
     this.#_btnSet.disableGroup('all');
   }
 
   /**
-   * @param {none}
-   * @returns {none}
+   * @returns {void}
    * @description Enables all buttons.
    */
-  enableAll(){
+  enableAll() {
     this.#_btnSet.enableGroup('all');
   }
 
   /**
-   * @param {ID_STRING}
-   * @param {func}
-   * @returns {none}
+   * @param {string} name - event name
+   * @param {func} evnt - a callback function
+   * @returns {void}
    * @description Sets a callback function to handle event.
    */
-  on(name, evnt){
+  on(name, evnt) {
     pushEventHandler(this.#_events, name, evnt);
   }
 };