@cntwg/html-helper 0.0.20 → 0.0.21

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

@@ -1,4 +1,4 @@
-// [v0.1.047-20230614]
+// [v0.1.049-20240713]
 
 // === module init block ===
 
@@ -31,14 +31,37 @@ const BTS_DEF_GROUP_NAME = 'all';
 
 // === module extra block (function definitions) ===
 
-// === module main block (function definitions) ===
+// === module main block ===
 
-// === module main block (class definitions) ===
+/***
+ * (* constant definitions *)
+ */
 
+/***
+ * (* function definitions *)
+ */
+
+/***
+ * (* class definitions *)
+ */
+
+/**
+ * @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>.
+ */
 class THtmlListButtonsController {
   #_btnSet = null;
   #_events = null;
 
+  /**
+   * @param {object} opt
+   * @param {HTMLElement} opt.btnFirst
+   * @param {HTMLElement} opt.btnPrev
+   * @param {HTMLElement} opt.btnNext
+   * @param {HTMLElement} opt.btnLast
+   */
   constructor(opt) {
     // load options
     const _options = isPlainObject(opt) ? opt : {};
@@ -48,25 +71,11 @@ class THtmlListButtonsController {
       btnPrev,
       btnNext,
       btnLast,
-      btn_frst, //* will deprecate
-      btn_prev, //* will deprecate
-      btn_next, //* will deprecate
-      btn_last, //* will deprecate
     } = _options;
-    if (btnFirst === undefined) btnFirst = btn_frst;
-    if (btnPrev === undefined) btnPrev = btn_prev;
-    if (btnNext === undefined) btnNext = btn_next;
-    if (btnLast === undefined) btnLast = btn_last;
     if (!isHTMLButton(btnFirst)) btnFirst = null;
     if (!isHTMLButton(btnPrev)) btnPrev = null;
     if (!isHTMLButton(btnNext)) btnNext = null;
     if (!isHTMLButton(btnLast)) btnLast = null;
-    /*const controls = {
-      btnFirst,
-      btnPrev,
-      btnNext,
-      btnLast,
-    };*/ // // TODO: ???
     // init buttons set
     const _btnSet = new THtmlButtonsSet();
     this.#_btnSet = _btnSet;
@@ -98,6 +107,12 @@ class THtmlListButtonsController {
     this.#_events = new Map();
   }
 
+  /**
+   * @param {object}
+   * @param {ID_STRING}
+   * @returns {none}
+   * @private
+   */
   #_on_btn_pressed = (e, key) => {
     //console.log(`THtmlListButtonsController._on_btn_pressed().key(${key}) ==> was called...`);
     //e.preventDefault(); /* need to reconsider reason for use */
@@ -111,38 +126,81 @@ class THtmlListButtonsController {
     };
   }
 
+  /**
+   * @param {ID_STRING}
+   * @param {...any}
+   * @returns {none}
+   * @private
+   * @see triggerEventHandler
+   */
   #_triggerEvent = (name, ...args) => {
     triggerEventHandler(this.#_events, name, ...args);
   }
 
+  /**
+   * @param {none}
+   * @returns {none}
+   * @description Disables all buttons.
+   */
   disableAll(){
     const _btnSet = this.#_btnSet;
     _btnSet.disableGroup('move_bkwd');
     _btnSet.disableGroup('move_frwd');
   }
 
+  /**
+   * @param {none}
+   * @returns {none}
+   * @description Disables all buttons in 'move_bkwd' group.
+   */
   disableBkwd(){
     this.#_btnSet.disableGroup('move_bkwd');
   }
 
+  /**
+   * @param {none}
+   * @returns {none}
+   * @description Disables all buttons in 'move_frwd' group.
+   */
   disableFrwd(){
     this.#_btnSet.disableGroup('move_frwd');
   }
 
+  /**
+   * @param {none}
+   * @returns {none}
+   * @description Enables all buttons.
+   */
   enableAll(){
     const _btnSet = this.#_btnSet;
     _btnSet.enableGroup('move_bkwd');
     _btnSet.enableGroup('move_frwd');
   }
 
+  /**
+   * @param {none}
+   * @returns {none}
+   * @description Enables all buttons in 'move_bkwd' group.
+   */
   enableBkwd(){
     this.#_btnSet.enableGroup('move_bkwd');
   }
 
+  /**
+   * @param {none}
+   * @returns {none}
+   * @description Enables all buttons in 'move_frwd' group.
+   */
   enableFrwd(){
     this.#_btnSet.enableGroup('move_frwd');
   }
 
+  /**
+   * @param {ID_STRING}
+   * @param {func}
+   * @returns {none}
+   * @description Sets a callback function to handle event.
+   */
   on(name, evnt){
     pushEventHandler(this.#_events, name, evnt);
   }

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

@@ -1,4 +1,4 @@
-// [v0.1.039-20230409]
+// [v0.1.042-20240705]
 
 // === module init block ===
 
@@ -24,24 +24,51 @@ const {
 
 // === module extra block (helper functions) ===
 
-// === module main block (function definitions) ===
+// === module main block ===
 
-// === module main block (class definitions) ===
+/***
+ * (* constant definitions *)
+ */
 
+/***
+ * (* function definitions *)
+ */
+
+/***
+ * (* class definitions *)
+ */
+
+/**
+ * @description This class implements an instance of a stub-items set
+ */
 class THtmlStubItemsSet {
   #_host = null;
   #_items = null;
   #_defItem = '';
   #_shownItem = null;
 
-  constructor(host, items) {
+  /**
+   * @param {HTMLElement}
+   * @param {(array|object)} opt
+   * @param {(array|object)} opt.items
+   * @param {ID_STRING} opt.defaultItem
+   * @param {bool} opt.force
+   */
+  constructor(host, opt) {
     this.#_host = isHTMLElement(host) ? host : null;
     this.#_items = new Map();
     this.#_defItem = '';
     this.#_shownItem = null;
-    if (isObject(items)) this.loadItems(items);
+    if (isObject(opt)) {
+      const obj = isArray(opt) ? { items: opt } : opt;
+      const { items, defaultItem, force } = obj;
+      this.loadItems(items, { defaultItem, force });
+    };
   }
 
+  /**
+   * @property {ID_STRING}
+   */
   get defItem(){
     return this.#_defItem;
   }
@@ -50,10 +77,19 @@ class THtmlStubItemsSet {
     this.setDefItem(name);
   }
 
+  /**
+   * @property {number}
+   * @readonly
+   */
   get count(){
     return this.#_items.size;
   }
 
+  /**
+   * @param {none}
+   * @returns {none}
+   * @description Clears an instance content.
+   */
   clear(){
     // // TODO: check if any item is shown
     this.#_items.clear();
@@ -61,6 +97,11 @@ class THtmlStubItemsSet {
     this.#_shownItem = null;
   }
 
+  /**
+   * @param {ID_STRING}
+   * @returns {bool}
+   * @description Sets a default item.
+   */
   setDefItem(name){
     let isACCEPTED = false;
     if (typeof name === 'string') {
@@ -71,26 +112,53 @@ class THtmlStubItemsSet {
     return isACCEPTED;
   }
 
+  /**
+   * @param {none}
+   * @returns {none}
+   * @description Resets a default item.
+   */
   rstDefItem(){
     // // TODO: check if item is shown
     this.#_defItem = '';
   }
 
+  /**
+   * @param {ID_STRING}
+   * @returns {bool}
+   * @description Checks if an item exists.
+   */
   hasItem(name){
     const _name = typeof name === 'string' ? name.trim() : '';
     return this.#_items.has(_name);
   }
 
+  /**
+   * @param {none}
+   * @returns {none}
+   * @description Checks if any items exists.
+   */
   hasItems(){
     return this.#_items.size > 0;
   }
 
+  /**
+   * @param {ID_STRING}
+   * @returns {?HTMLElement}
+   * @description Returns an item by its 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}
+   * @description Adds an item to an instance members.
+   */
   addItem(name, item, opt){
     const _name = typeof name === 'string' ? name.trim() : '';
     let isSUCCEED = false;
@@ -104,6 +172,11 @@ class THtmlStubItemsSet {
     return isSUCCEED;
   }
 
+  /**
+   * @param {ID_STRING}
+   * @returns {bool}
+   * @description Deletes an item from an instance members.
+   */
   delItem(name){
     let _name = '';
     let isSUCCEED = (
@@ -117,6 +190,11 @@ class THtmlStubItemsSet {
     return isSUCCEED;
   }
 
+  /**
+   * @param {ID_STRING}
+   * @returns {bool}
+   * @description Shows an item.
+   */
   showItem(name){
     const item = this.getItem(name);
     const isSUCCEED = this.#_host && item ? true : false;
@@ -124,10 +202,20 @@ class THtmlStubItemsSet {
     return isSUCCEED;
   }
 
+  /**
+   * @param {none}
+   * @returns {bool}
+   * @description Shows a default item.
+   */
   showDefItem(){
     return this.showItem(this.#_defItem);
   }
 
+  /**
+   * @param {ID_STRING}
+   * @returns {bool}
+   * @description Hides an item.
+   */
   hideItem(name){
     const item = this.getItem(name);
     const isSUCCEED = this.#_host && item ? true : false;
@@ -135,10 +223,24 @@ class THtmlStubItemsSet {
     return isSUCCEED;
   }
 
+  /**
+   * @param {none}
+   * @returns {bool}
+   * @description Hides a default item.
+   */
   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}
+   * @description Adds an items to an instance members.
+   */
   loadItems(list, opt){
     let _options = opt;
     if (typeof _options === 'boolean') _options = { useClear: _options };
@@ -147,9 +249,9 @@ class THtmlStubItemsSet {
       defaultItem,
       useClear,
       force,
-      load_as_new, //* will deprecate
+      //load_as_new, //* will deprecate
     } = _options;
-    if (useClear === undefined) useClear = load_as_new;
+    //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,11 +1,27 @@
-// [v0.1.060-20230614]
+// [v0.1.061-20240705]
 
 // === module init block ===
 
 // === module extra block (helper functions) ===
 
-// === module main block (function definitions) ===
+// === module main block ===
 
+/***
+ * (* constant definitions *)
+ */
+
+/***
+ * (* 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') {
@@ -19,6 +35,14 @@ function pushEventHandler(pool, name, evnt){
   };
 };
 
+/**
+ * @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 !== '') {
@@ -26,6 +50,12 @@ function triggerEventHandler(pool, name, ...args){
   };
 };
 
+/**
+ * @function readOnClickEventInfo
+ * @param {object}
+ * @returns {object}
+ * @inner
+ */
 function readOnClickEventInfo(e) {
   let item = null;
   const { eventPhase, detail: onClickNum } = e;
@@ -51,7 +81,9 @@ function readOnClickEventInfo(e) {
   return { item, onClickNum };
 };
 
-// === module main block (class definitions) ===
+/***
+ * (* class definitions *)
+ */
 
 // === module exports block ===