@cntwg/html-helper 0.0.25 → 0.0.27

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

@@ -1,4 +1,4 @@
-// [v0.1.053-20250416]
+// [v0.1.056-20250827]
 
 // === module init block ===
 
@@ -7,11 +7,11 @@ const {
 } = require('@ygracs/bsfoc-lib-js');
 
 const {
+  isHTMLButton,
   CSS_CLASS_STRING,
 } = require('../html-helper-lib.js');
 
 const {
-  isHTMLButton,
   THtmlButtonsSet,
 }  = require('./buttons.js');
 
@@ -42,6 +42,15 @@ const BTS_DEF_GROUP_NAME = 'all';
  * (* class definitions *)
  */
 
+/**
+ * A description for list buttons set.
+ * @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'
+ */
+
 /**
  * @classdesc This class implements an interface of a pre-defined
  *            buttons set that is used in pair with a list elements.
@@ -54,21 +63,10 @@ class THtmlListButtonsController {
   #_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.
-   */
-
-  /**
+   * Creates an instance of a buttons set.
    * @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 {
@@ -76,7 +74,7 @@ class THtmlListButtonsController {
       btnPrev,
       btnNext,
       btnLast,
-    } = _options;
+    } = isPlainObject(opt) ? opt : {};
     if (!isHTMLButton(btnFirst)) btnFirst = null;
     if (!isHTMLButton(btnPrev)) btnPrev = null;
     if (!isHTMLButton(btnNext)) btnNext = null;
@@ -143,8 +141,8 @@ class THtmlListButtonsController {
   }
 
   /**
+   * Disables all buttons.
    * @returns {void}
-   * @description Disables all buttons.
    */
   disableAll() {
     const _btnSet = this.#_btnSet;
@@ -153,24 +151,24 @@ class THtmlListButtonsController {
   }
 
   /**
+   * Disables all buttons in 'move_bkwd' group.
    * @returns {void}
-   * @description Disables all buttons in 'move_bkwd' group.
    */
   disableBkwd() {
     this.#_btnSet.disableGroup('move_bkwd');
   }
 
   /**
+   * Disables all buttons in 'move_frwd' group.
    * @returns {void}
-   * @description Disables all buttons in 'move_frwd' group.
    */
   disableFrwd() {
     this.#_btnSet.disableGroup('move_frwd');
   }
 
   /**
+   * Enables all buttons.
    * @returns {void}
-   * @description Enables all buttons.
    */
   enableAll() {
     const _btnSet = this.#_btnSet;
@@ -179,26 +177,26 @@ class THtmlListButtonsController {
   }
 
   /**
+   * Enables all buttons in 'move_bkwd' group.
    * @returns {void}
-   * @description Enables all buttons in 'move_bkwd' group.
    */
   enableBkwd() {
     this.#_btnSet.enableGroup('move_bkwd');
   }
 
   /**
+   * Enables all buttons in 'move_frwd' group.
    * @returns {void}
-   * @description Enables all buttons in 'move_frwd' group.
    */
   enableFrwd() {
     this.#_btnSet.enableGroup('move_frwd');
   }
 
   /**
+   * Sets a callback function to handle event.
    * @param {string} name - event name
    * @param {func} evnt - callback function
    * @returns {void}
-   * @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.046-20250416]
+// [v0.1.050-20250827]
 
 // === module init block ===
 
@@ -27,11 +27,27 @@ const {
  */
 
 /**
+ * A settings to load a stub-elements.
  * @typedef {Object} OPT_ldstubs
- * @property {string} [defaultItem] - a default element name
+ * @property {string} [defaultItem] - <*deprecated*> 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.
+ * @todo [since v0.0.26] `defaultItem`-option deprecated
+ */
+
+/**
+ * A stub-elements description list.
+ * @typedef {Object} OBJ_stubEList
+ * @property {Array} items - array of `name`-`element` pairs
+ * @property {string} [defaultItem] - a default element name
+ */
+
+/**
+ * A an options set for a `THtmlStubItemsSet`-class constructor
+ * @typedef {Object} OPT_stubconsett
+ * @property {(any[])} items - array of `name`-`element` pairs
+ * @property {string} [defaultItem] - a default element name
+ * @property {boolean} [force=false] - run in a force mode
  */
 
 /**
@@ -47,19 +63,10 @@ class THtmlStubItemsSet {
   #_shownItem = null;
 
   /**
-   * @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 - options
-   * @param {(array|object)} opt.items
-   * @param {string} opt.defaultItem
-   * @param {boolean} opt.force - <*deprecated (since: v0.0.23)*>
-   * @description Creates an instance of a stub-items set
+   * Creates an instance of a stub-items set
+   * @param {HTMLElement} host - host element
+   * @param {(array|OPT_stubconsett|OBJ_stubEList)} [opt] - options
+   * @todo [since v0.0.26] use of an `array`-type as a value of an `opt` is deprecated
    */
   constructor(host, opt) {
     this.#_host = isHTMLElement(host) ? host : null;
@@ -67,9 +74,15 @@ class THtmlStubItemsSet {
     this.#_defItem = '';
     this.#_shownItem = null;
     if (isObject(opt)) {
+      /** @type {(OPT_stubconsett|OBJ_stubEList)} */
       const obj = isArray(opt) ? { items: opt } : opt;
       const { items, defaultItem, force } = obj;
-      this.loadItems(items, { defaultItem, force });
+      this.loadItems({
+        items,
+        defaultItem,
+      }, {
+        force,
+      });
     };
   }
 
@@ -95,8 +108,8 @@ class THtmlStubItemsSet {
   }
 
   /**
+   * Clears an instance content.
    * @returns {void}
-   * @description Clears an instance content.
    */
   clear() {
     // // TODO: check if any item is shown
@@ -106,9 +119,9 @@ class THtmlStubItemsSet {
   }
 
   /**
+   * Sets a default item.
    * @param {string} name - an element name
    * @returns {boolean}
-   * @description Sets a default item.
    */
   setDefItem(name) {
     let isACCEPTED = false;
@@ -121,8 +134,8 @@ class THtmlStubItemsSet {
   }
 
   /**
+   * Resets a default item.
    * @returns {void}
-   * @description Resets a default item.
    */
   rstDefItem() {
     // // TODO: check if item is shown
@@ -130,9 +143,9 @@ class THtmlStubItemsSet {
   }
 
   /**
+   * Checks if an item exists.
    * @param {string} name - an element name
    * @returns {boolean}
-   * @description Checks if an item exists.
    */
   hasItem(name) {
     const _name = typeof name === 'string' ? name.trim() : '';
@@ -140,17 +153,17 @@ class THtmlStubItemsSet {
   }
 
   /**
+   * Checks if any items exists.
    * @returns {boolean}
-   * @description Checks if any items exists.
    */
   hasItems() {
     return this.#_items.size > 0;
   }
 
   /**
+   * Returns an item by its name.
    * @param {string} name - an element name
    * @returns {?HTMLElement}
-   * @description Returns an item by its name.
    */
   getItem(name) {
     const _name = typeof name === 'string' ? name.trim() : '';
@@ -159,11 +172,11 @@ class THtmlStubItemsSet {
   }
 
   /**
+   * Adds an item to an instance members.
    * @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) {
     const _name = typeof name === 'string' ? name.trim() : '';
@@ -179,9 +192,9 @@ class THtmlStubItemsSet {
   }
 
   /**
+   * Deletes an item from an instance members.
    * @param {string} name - an element name
    * @returns {boolean}
-   * @description Deletes an item from an instance members.
    */
   delItem(name) {
     let _name = '';
@@ -197,9 +210,9 @@ class THtmlStubItemsSet {
   }
 
   /**
+   * Shows an item.
    * @param {string} name - an element name
    * @returns {boolean}
-   * @description Shows an item.
    */
   showItem(name) {
     const item = this.getItem(name);
@@ -209,17 +222,17 @@ class THtmlStubItemsSet {
   }
 
   /**
+   * Shows a default item.
    * @returns {boolean}
-   * @description Shows a default item.
    */
   showDefItem() {
     return this.showItem(this.#_defItem);
   }
 
   /**
+   * Hides an item.
    * @param {string} name - an element name
    * @returns {boolean}
-   * @description Hides an item.
    */
   hideItem(name) {
     const item = this.getItem(name);
@@ -229,41 +242,41 @@ class THtmlStubItemsSet {
   }
 
   /**
+   * Hides a default item.
    * @returns {boolean}
-   * @description Hides a default item.
    */
   hideDefItem() {
     return this.hideItem(this.#_defItem);
   }
 
   /**
-   * @param {(Array|OBJ_stubEList)} list - an array of entries or special object
+   * Adds an items to an instance members.
+   * @param {(Array|OBJ_stubEList)} data - an array of entries or special object
    * @param {(boolean|OPT_ldstubs)} [opt] - an options
    * @returns {number}
-   * @description Adds an items to an instance members.
    * @todo [since 0.0.25] deprecate use of `opt` as `boolean`
+   * @todo [since v0.0.26] for `OPT_ldstubs` a `defaultItem`-option deprecated
    */
-  loadItems(list, opt) {
-    let _options = opt;
-    if (typeof _options === 'boolean') _options = { useClear: _options };
-    if (!isPlainObject(_options)) _options = {};
-    /** @type {OPT_ldstubs} */
+  loadItems(data, opt) {
+    /** @type {OBJ_stubEList} */
     let {
+      items,
       defaultItem,
+    } = isPlainObject(data) ? data : { items: data };
+    /** @type {OPT_ldstubs} */
+    let _options = isPlainObject(opt) ? opt : { useClear: opt };
+    let {
       useClear,
       force,
     } = _options;
     if (typeof useClear !== 'boolean') useClear = true;
     if (typeof force !== 'boolean') force = false;
-    let _list = list;
-    if (isPlainObject(_list)) {
-      ({ items: _list, defaultItem } = _list);
-    };
+    if (defaultItem === undefined) defaultItem = _options.defaultItem;  /* deprecated */
     const setDefs = defaultItem !== undefined;
     let count = 0;
-    if (isArray(_list)) {
+    if (isArray(items)) {
       if (useClear) this.clear();
-      _list.forEach((obj) => {
+      items.forEach((obj) => {
         if (isArray(obj)) {
           const [ name, item ] = obj;
           if (this.addItem(name, item, force)) count++;