@cntwg/html-helper 0.0.22 → 0.0.23

package/lib/html-ctrls/lists-btn.js

@@ -1,4 +1,4 @@
-// [v0.1.049-20240713]
+// [v0.1.052-20241119]
 
 // === module init block ===
 
@@ -7,7 +7,6 @@ const {
 } = require('@ygracs/bsfoc-lib-js');
 
 const {
-  isHTMLElement,
   CSS_CLASS_STRING,
 } = require('../html-helper-lib.js');
 
@@ -22,13 +21,9 @@ const {
 } = require('./mod-hfunc.js');
 
 const {
-  //CSS_CLASS_SELECTED,
   CSS_CLASS_DISABLED,
-  //CSS_CLASS_HIDDEN,
 } = CSS_CLASS_STRING;
 
-const BTS_DEF_GROUP_NAME = 'all';
-
 // === module extra block (function definitions) ===
 
 // === module main block ===
@@ -37,6 +32,8 @@ const BTS_DEF_GROUP_NAME = 'all';
  * (* constant definitions *)
  */
 
+const BTS_DEF_GROUP_NAME = 'all';
+
 /***
  * (* function definitions *)
  */
@@ -46,26 +43,34 @@ const BTS_DEF_GROUP_NAME = 'all';
  */
 
 /**
- * @description This class implements an instance of a pre-defined
- *              buttons set that is used in pair with a list elements.
- *              A set provide a buttons: <next>, <previous>, <first>
- *              and <last>.
+ * @classdesc This class implements an interface of a pre-defined
+ *            buttons set that is used in pair with a list elements.
+ *            A set provide a buttons: <next>, <previous>, <first> and <last>.
  */
 class THtmlListButtonsController {
-  #_btnSet = null;
-  #_events = null;
+  /** @property {THtmlButtonsSet} */
+  #_btnSet;
+  /** @property {Map} */
+  #_events;
+
+  /**
+   * @typedef {Object} listButtonsSetDesc
+   * @property {?HTMLElement} btnFirst - button 'move to first'
+   * @property {?HTMLElement} btnPrev - button 'move to previous'
+   * @property {?HTMLElement} btnNext - button 'move to next'
+   * @property {?HTMLElement} btnLast - button 'move to last'
+   * @description A description for list buttons set.
+   */
 
   /**
-   * @param {object} opt
-   * @param {HTMLElement} opt.btnFirst
-   * @param {HTMLElement} opt.btnPrev
-   * @param {HTMLElement} opt.btnNext
-   * @param {HTMLElement} opt.btnLast
+   * @param {listButtonsSetDesc} [opt] - an options
+   * @description Creates an instance of a buttons set.
    */
   constructor(opt) {
     // load options
     const _options = isPlainObject(opt) ? opt : {};
     // load controls
+    /** @type {listButtonsSetDesc} */
     let {
       btnFirst,
       btnPrev,
@@ -108,9 +113,9 @@ class THtmlListButtonsController {
   }
 
   /**
-   * @param {object}
-   * @param {ID_STRING}
-   * @returns {none}
+   * @param {object} e - event
+   * @param {string} key - button ID
+   * @returns {void}
    * @private
    */
   #_on_btn_pressed = (e, key) => {
@@ -127,9 +132,9 @@ class THtmlListButtonsController {
   }
 
   /**
-   * @param {ID_STRING}
-   * @param {...any}
-   * @returns {none}
+   * @param {string} name - event name
+   * @param {...any} args
+   * @returns {void}
    * @private
    * @see triggerEventHandler
    */
@@ -138,70 +143,64 @@ class THtmlListButtonsController {
   }
 
   /**
-   * @param {none}
-   * @returns {none}
+   * @returns {void}
    * @description Disables all buttons.
    */
-  disableAll(){
+  disableAll() {
     const _btnSet = this.#_btnSet;
     _btnSet.disableGroup('move_bkwd');
     _btnSet.disableGroup('move_frwd');
   }
 
   /**
-   * @param {none}
-   * @returns {none}
+   * @returns {void}
    * @description Disables all buttons in 'move_bkwd' group.
    */
-  disableBkwd(){
+  disableBkwd() {
     this.#_btnSet.disableGroup('move_bkwd');
   }
 
   /**
-   * @param {none}
-   * @returns {none}
+   * @returns {void}
    * @description Disables all buttons in 'move_frwd' group.
    */
-  disableFrwd(){
+  disableFrwd() {
     this.#_btnSet.disableGroup('move_frwd');
   }
 
   /**
-   * @param {none}
-   * @returns {none}
+   * @returns {void}
    * @description Enables all buttons.
    */
-  enableAll(){
+  enableAll() {
     const _btnSet = this.#_btnSet;
     _btnSet.enableGroup('move_bkwd');
     _btnSet.enableGroup('move_frwd');
   }
 
   /**
-   * @param {none}
-   * @returns {none}
+   * @returns {void}
    * @description Enables all buttons in 'move_bkwd' group.
    */
-  enableBkwd(){
+  enableBkwd() {
     this.#_btnSet.enableGroup('move_bkwd');
   }
 
   /**
-   * @param {none}
-   * @returns {none}
+   * @returns {void}
    * @description Enables all buttons in 'move_frwd' group.
    */
-  enableFrwd(){
+  enableFrwd() {
     this.#_btnSet.enableGroup('move_frwd');
   }
 
   /**
-   * @param {ID_STRING}
-   * @param {func}
-   * @returns {none}
+   * @param {string} name - event name
+   * @param {func} evnt - callback function
+   * @returns {void}
    * @description Sets a callback function to handle event.
    */
-  on(name, evnt){
+  on(name, evnt) {
     pushEventHandler(this.#_events, name, evnt);
   }
 };

package/lib/html-ctrls/lists-stubs.js

@@ -1,27 +1,15 @@
-// [v0.1.042-20240705]
+// [v0.1.045-20241119]
 
 // === module init block ===
 
 const {
-  //readAsBool, readAsNumber, readAsString,
-  //isEmptyString, isNotEmptyString,
   isArray, isObject, isPlainObject,
 } = require('@ygracs/bsfoc-lib-js');
 
 const {
   isHTMLElement,
-  //isSelectedHTMLElement, isHiddenHTMLElement,
-  //showHtmlElement, hideHtmlElement,
-  //selectHtmlElement, unselectHtmlElement,
-  CSS_CLASS_STRING,
 } = require('../html-helper-lib.js');
 
-/*const {
-  CSS_CLASS_SELECTED,
-  CSS_CLASS_DISABLED,
-  CSS_CLASS_HIDDEN,
-} = CSS_CLASS_STRING;*/
-
 // === module extra block (helper functions) ===
 
 // === module main block ===
@@ -39,20 +27,31 @@ const {
  */
 
 /**
- * @description This class implements an instance of a stub-items set
+ * @classdesc This class implements an interface of a stub-items set
  */
 class THtmlStubItemsSet {
-  #_host = null;
-  #_items = null;
-  #_defItem = '';
+  /** @property {?HTMLElement} */
+  #_host;
+  /** @property {Map} */
+  #_items;
+  /** @property {string} */
+  #_defItem;
   #_shownItem = null;
 
   /**
-   * @param {HTMLElement}
-   * @param {(array|object)} opt
+   * @typedef {Object} OBJ_stubEList
+   * @property {Array} items - array of `name`-`element` pairs
+   * @property {string} [defaultItem] - a default element name
+   * @description A stub-elements description list.
+   */
+
+  /**
+   * @param {HTMLElement} host
+   * @param {(array|object|OBJ_stubEList)} opt
    * @param {(array|object)} opt.items
-   * @param {ID_STRING} opt.defaultItem
-   * @param {bool} opt.force
+   * @param {string} opt.defaultItem
+   * @param {boolean} opt.force - <*deprecated (since: v0.0.23)*>
+   * @description Creates an instance of a stub-items set
    */
   constructor(host, opt) {
     this.#_host = isHTMLElement(host) ? host : null;
@@ -67,30 +66,31 @@ class THtmlStubItemsSet {
   }
 
   /**
-   * @property {ID_STRING}
+   * @property {string}
+   * @description Defines a default element name
    */
-  get defItem(){
+  get defItem() {
     return this.#_defItem;
   }
 
-  set defItem(name){
+  set defItem(name) {
     this.setDefItem(name);
   }
 
   /**
    * @property {number}
    * @readonly
+   * @description Contains a Qty of an elements
    */
-  get count(){
+  get count() {
     return this.#_items.size;
   }
 
   /**
-   * @param {none}
-   * @returns {none}
+   * @returns {void}
    * @description Clears an instance content.
    */
-  clear(){
+  clear() {
     // // TODO: check if any item is shown
     this.#_items.clear();
     this.#_defItem = '';
@@ -98,11 +98,11 @@ class THtmlStubItemsSet {
   }
 
   /**
-   * @param {ID_STRING}
-   * @returns {bool}
+   * @param {string} name - an element name
+   * @returns {boolean}
    * @description Sets a default item.
    */
-  setDefItem(name){
+  setDefItem(name) {
     let isACCEPTED = false;
     if (typeof name === 'string') {
       const _name = name.trim();
@@ -113,53 +113,51 @@ class THtmlStubItemsSet {
   }
 
   /**
-   * @param {none}
-   * @returns {none}
+   * @returns {void}
    * @description Resets a default item.
    */
-  rstDefItem(){
+  rstDefItem() {
     // // TODO: check if item is shown
     this.#_defItem = '';
   }
 
   /**
-   * @param {ID_STRING}
-   * @returns {bool}
+   * @param {string} name - an element name
+   * @returns {boolean}
    * @description Checks if an item exists.
    */
-  hasItem(name){
+  hasItem(name) {
     const _name = typeof name === 'string' ? name.trim() : '';
     return this.#_items.has(_name);
   }
 
   /**
-   * @param {none}
-   * @returns {none}
+   * @returns {boolean}
    * @description Checks if any items exists.
    */
-  hasItems(){
+  hasItems() {
     return this.#_items.size > 0;
   }
 
   /**
-   * @param {ID_STRING}
+   * @param {string} name - an element name
    * @returns {?HTMLElement}
    * @description Returns an item by its name.
    */
-  getItem(name){
+  getItem(name) {
     const _name = typeof name === 'string' ? name.trim() : '';
     const item = this.#_items.has(_name) ? this.#_items.get(_name) : null;
     return isHTMLElement(item) ? item : null;
   }
 
   /**
-   * @param {ID_STRING}
-   * @param {HTMLElement}
-   * @param {bool}
-   * @returns {bool}
+   * @param {string} name - an element name
+   * @param {HTMLElement} item - an element
+   * @param {boolean} [opt=false] - flag indicating a force mode
+   * @returns {boolean}
    * @description Adds an item to an instance members.
    */
-  addItem(name, item, opt){
+  addItem(name, item, opt) {
     const _name = typeof name === 'string' ? name.trim() : '';
     let isSUCCEED = false;
     if (_name !== '' && isHTMLElement(item)) {
@@ -173,11 +171,11 @@ class THtmlStubItemsSet {
   }
 
   /**
-   * @param {ID_STRING}
-   * @returns {bool}
+   * @param {string} name - an element name
+   * @returns {boolean}
    * @description Deletes an item from an instance members.
    */
-  delItem(name){
+  delItem(name) {
     let _name = '';
     let isSUCCEED = (
       typeof name === 'string'
@@ -191,11 +189,11 @@ class THtmlStubItemsSet {
   }
 
   /**
-   * @param {ID_STRING}
-   * @returns {bool}
+   * @param {string} name - an element name
+   * @returns {boolean}
    * @description Shows an item.
    */
-  showItem(name){
+  showItem(name) {
     const item = this.getItem(name);
     const isSUCCEED = this.#_host && item ? true : false;
     if (isSUCCEED) this.#_host.append(item);
@@ -203,20 +201,19 @@ class THtmlStubItemsSet {
   }
 
   /**
-   * @param {none}
-   * @returns {bool}
+   * @returns {boolean}
    * @description Shows a default item.
    */
-  showDefItem(){
+  showDefItem() {
     return this.showItem(this.#_defItem);
   }
 
   /**
-   * @param {ID_STRING}
-   * @returns {bool}
+   * @param {string} name - an element name
+   * @returns {boolean}
    * @description Hides an item.
    */
-  hideItem(name){
+  hideItem(name) {
     const item = this.getItem(name);
     const isSUCCEED = this.#_host && item ? true : false;
     if (isSUCCEED && this.#_host.contains(item)) item.remove();
@@ -224,34 +221,37 @@ class THtmlStubItemsSet {
   }
 
   /**
-   * @param {none}
-   * @returns {bool}
+   * @returns {boolean}
    * @description Hides a default item.
    */
-  hideDefItem(){
+  hideDefItem() {
     return this.hideItem(this.#_defItem);
   }
 
   /**
-   * @param {(array|object)}
-   * @param {(bool|object)} [opt]
-   * @param {ID_STRING} [opt.defaultItem]
-   * @param {bool} [opt.useClear=true]
-   * @param {bool} [opt.force=false]
-   * @returns {count}
+   * @typedef {Object} OPT_ldstubs
+   * @property {string} [defaultItem] - a default element name
+   * @property {boolean} [useClear=true] - to clear before load an elements
+   * @property {boolean} [force=false] - run in a force mode
+   * @description A settings to load stub-elements.
+   */
+
+  /**
+   * @param {(Array|OBJ_stubEList)} list - an array of entries or special object
+   * @param {(boolean|OPT_ldstubs)} [opt] - an options
+   * @returns {number}
    * @description Adds an items to an instance members.
    */
-  loadItems(list, opt){
+  loadItems(list, opt) {
     let _options = opt;
     if (typeof _options === 'boolean') _options = { useClear: _options };
     if (!isPlainObject(_options)) _options = {};
+    /** @type {OPT_ldstubs} */
     let {
       defaultItem,
       useClear,
       force,
-      //load_as_new, //* will deprecate
     } = _options;
-    //if (useClear === undefined) useClear = load_as_new;
     if (typeof useClear !== 'boolean') useClear = true;
     if (typeof force !== 'boolean') force = false;
     let _list = list;

package/lib/html-ctrls/mod-hfunc.js

@@ -1,7 +1,11 @@
-// [v0.1.061-20240705]
+// [v0.1.062-20241115]
 
 // === module init block ===
 
+const {
+  pushEventHandler, triggerEventHandler,
+} = require('../event-hfunc.js');
+
 // === module extra block (helper functions) ===
 
 // === module main block ===
@@ -14,42 +18,6 @@
  * (* function definitions *)
  */
 
-/**
- * @function pushEventHandler
- * @param {object}
- * @param {ID_STRING}
- * @param {func}
- * @returns {none}
- * @inner
- */
-function pushEventHandler(pool, name, evnt){
-  const _name = typeof name === 'string' ? name.trim() : '';
-  if (_name !== '' && typeof evnt === 'function') {
-    if (!pool.has(_name)) {
-      pool.set(_name, evnt);
-    } else {
-      /* NOTE:
-       *    for current you can't reset or set new one on the same event
-       */
-    };
-  };
-};
-
-/**
- * @function triggerEventHandler
- * @param {object}
- * @param {ID_STRING}
- * @param {...any}
- * @returns {none}
- * @inner
- */
-function triggerEventHandler(pool, name, ...args){
-  const _name = typeof name === 'string' ? name.trim() : '';
-  if (_name !== '') {
-    if (pool.has(_name)) pool.get(_name)(...args);
-  };
-};
-
 /**
  * @function readOnClickEventInfo
  * @param {object}
@@ -87,6 +55,8 @@ function readOnClickEventInfo(e) {
 
 // === module exports block ===
 
+exports.readOnClickEventInfo = readOnClickEventInfo;
+
+// re-exported
 exports.pushEventHandler = pushEventHandler;
 exports.triggerEventHandler = triggerEventHandler;
-exports.readOnClickEventInfo = readOnClickEventInfo;